Engine Registration

Engines are the modular services that provide specific functionality in Sphere (chat, VoIP, drive, mail, activity, user management). Each engine registers itself with sphere-core so the orchestrator knows how to provision tenants and users. Engines can also push data back into sphere-core through message projection and event endpoints.

The engine registration and event endpoints are internal service-to-service APIs authenticated with HMAC signatures. They are not exposed through the Traefik gateway. See the HMAC overview for authentication details. The list engines endpoint is public.

The engine model

Name
code
Type
string
Description
Unique identifier for the engine. One of: chat, voip, drive, mail, activity, usermanager.
Name
name
Type
string
Description
Human-readable display name of the engine.
Name
url
Type
string
Description
The internal base URL of the engine service (e.g., http://chat:7006).
Name
is_active
Type
boolean
Description
Whether the engine is currently active and available for provisioning.
Name
requires_tenant_provision
Type
boolean
Description
Whether the engine requires tenant-level provisioning when a new tenant is created.
Name
requires_user_provision
Type
boolean
Description
Whether the engine requires user-level provisioning when a new user is created.

The engine registry is seeded by EngineRegistrySeeder in sphere-core. All 6 engines are registered by default: chat, voip, drive, mail, activity, and usermanager. Each has is_active: true, requires_tenant_provision: true, and requires_user_provision: true.

GET/core/api/v1/engines

List registered engines

Retrieve the list of all engines registered in the platform. This is a public endpoint that does not require authentication. It returns the same data as the Health & Metrics engines endpoint.

Request

GET

/core/api/v1/engines

curl https://your-sphere.example.com/core/api/v1/engines

Response

{
  "data": [
    {
      "code": "chat",
      "name": "Chat",
      "url": "http://chat:7006",
      "is_active": true,
      "requires_tenant_provision": true,
      "requires_user_provision": true
    },
    {
      "code": "voip",
      "name": "VoIP",
      "url": "http://voip:7007",
      "is_active": true,
      "requires_tenant_provision": true,
      "requires_user_provision": true
    },
    {
      "code": "drive",
      "name": "Drive",
      "url": "http://drive:7008",
      "is_active": true,
      "requires_tenant_provision": true,
      "requires_user_provision": true
    },
    {
      "code": "mail",
      "name": "Mail",
      "url": "http://mail:7005",
      "is_active": true,
      "requires_tenant_provision": true,
      "requires_user_provision": true
    },
    {
      "code": "activity",
      "name": "Activity",
      "url": "http://activity:7009",
      "is_active": true,
      "requires_tenant_provision": true,
      "requires_user_provision": true
    },
    {
      "code": "usermanager",
      "name": "User Manager",
      "url": "http://usermanager:7004",
      "is_active": true,
      "requires_tenant_provision": true,
      "requires_user_provision": true
    }
  ]
}

POST/core/api/internal/engines/register

Register an engine

Register a new engine with sphere-core. This is typically done by the engine during its startup or by the EngineRegistrySeeder. Once registered, the orchestrator will include this engine in tenant and user provisioning flows.

Required attributes

Name
code
Type
string
Description
Unique code for the engine (e.g., chat, voip, drive). Must be lowercase, alphanumeric.
Name
name
Type
string
Description
Human-readable display name.
Name
url
Type
string
Description
The internal base URL where the engine is reachable (e.g., http://chat:7006).
Name
requires_tenant_provision
Type
boolean
Description
Whether the engine needs to be called during tenant provisioning.
Name
requires_user_provision
Type
boolean
Description
Whether the engine needs to be called during user provisioning.

Request

POST

/core/api/internal/engines/register

curl -X POST http://core:7002/api/internal/engines/register \
  -H "Content-Type: application/json" \
  -H "X-Sphere-Signature: t=1708800000,v1=abc123..." \
  -d '{
    "code": "chat",
    "name": "Chat",
    "url": "http://chat:7006",
    "requires_tenant_provision": true,
    "requires_user_provision": true
  }'

Response (201 Created)

{
  "data": {
    "code": "chat",
    "name": "Chat",
    "url": "http://chat:7006",
    "is_active": true,
    "requires_tenant_provision": true,
    "requires_user_provision": true
  }
}

POST/core/api/internal/messages/project

Project a message

Project a message from an engine into sphere-core's entity system. This is used by sphere-chat to create message projections that appear in the timeline and inbox of related entities.

When a message is sent in a chat room that is linked to an entity, sphere-chat calls this endpoint so the message appears in the entity's discussion timeline.

Required attributes

Name
tenant_id
Type
string (UUID)
Description
The tenant context for the message.
Name
entity_id
Type
string (UUID)
Description
The entity to project the message onto.
Name
message_id
Type
string
Description
The unique identifier of the message in the source engine (e.g., Matrix event ID).
Name
sender_id
Type
string (UUID)
Description
The user ID of the message sender.
Name
content
Type
string
Description
The message text content.
Name
sent_at
Type
string (ISO 8601)
Description
The timestamp when the message was sent.
Name
source
Type
string
Description
The engine that produced this message (e.g., chat, mail).

Request

POST

/core/api/internal/messages/project

curl -X POST http://core:7002/api/internal/messages/project \
  -H "Content-Type: application/json" \
  -H "X-Sphere-Signature: t=1708800000,v1=abc123..." \
  -d '{
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "entity_id": "c3d4e5f6-7890-1234-abcd-567890abcdef",
    "message_id": "$evt_abc123",
    "sender_id": "a7c8e9f0-1234-5678-abcd-ef0123456789",
    "content": "Updated the contact information for this client.",
    "sent_at": "2026-01-20T14:30:00Z",
    "source": "chat"
  }'

Response (201 Created)

{
  "data": {
    "id": "d4e5f6a7-8901-2345-bcde-f01234567890",
    "entity_id": "c3d4e5f6-7890-1234-abcd-567890abcdef",
    "message_id": "$evt_abc123",
    "source": "chat",
    "projected_at": "2026-01-20T14:30:01Z"
  }
}

POST/core/api/internal/mail/events

Receive mail events

Receive events from the sphere-mail engine. This endpoint allows sphere-mail to notify sphere-core about mail-related events (e.g., email received, email sent) that should be projected onto entities.

Required attributes

Name
tenant_id
Type
string (UUID)
Description
The tenant context for the event.
Name
event_type
Type
string
Description
The type of mail event (e.g., mail.received, mail.sent).
Name
payload
Type
object
Description
Event-specific payload containing mail details (subject, sender, recipients, entity associations).

Request

POST

/core/api/internal/mail/events

curl -X POST http://core:7002/api/internal/mail/events \
  -H "Content-Type: application/json" \
  -H "X-Sphere-Signature: t=1708800000,v1=abc123..." \
  -d '{
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "event_type": "mail.received",
    "payload": {
      "message_id": "<abc123@mail.example.com>",
      "subject": "Re: Project update",
      "from": "client@example.com",
      "to": ["alice@acme.local"],
      "entity_id": "c3d4e5f6-7890-1234-abcd-567890abcdef",
      "received_at": "2026-01-20T14:30:00Z"
    }
  }'

Response (202 Accepted)

{
  "data": {
    "event_type": "mail.received",
    "status": "accepted"
  }
}