Orchestration

The orchestration API manages the lifecycle of tenants and users across all Sphere engines. When a new tenant is created in sphere-auth, it calls sphere-core to orchestrate provisioning across all registered engines (chat, VoIP, drive, mail, activity, user manager).

These 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.

Orchestration model

Orchestration follows a best-effort pattern. Engine provisioning failures do not block or rollback the tenant creation. Each engine is provisioned independently, and failures are recorded for later retry.

Name
tenant_id
Type
string (UUID)
Description
The unique identifier of the tenant being provisioned or deprovisioned.
Name
tenant_short_id
Type
string
Description
The short human-readable slug for the tenant (e.g., acme).
Name
status
Type
string
Description
Provisioning status: pending, in_progress, completed, partial_failure, or failed.

POST/core/api/internal/orchestration/provision/tenant

Provision tenant

Trigger tenant provisioning across all registered engines. Sphere-core iterates through all engines that have requires_tenant_provision: true and calls each engine's internal provision endpoint sequentially.

This endpoint is called by sphere-auth after creating the tenant locally. The orchestration is best-effort -- individual engine failures are recorded but do not block other engines from being provisioned.

Required attributes

Name
tenant_id
Type
string (UUID)
Description
The UUID of the tenant to provision.
Name
tenant_short_id
Type
string
Description
The short slug identifier for the tenant.
Name
name
Type
string
Description
The display name of the tenant.

Request

POST

/core/api/internal/orchestration/provision/tenant

curl -X POST http://core:7002/api/internal/orchestration/provision/tenant \
  -H "Content-Type: application/json" \
  -H "X-Sphere-Signature: t=1708800000,v1=abc123..." \
  -d '{
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "tenant_short_id": "acme",
    "name": "Acme Corp"
  }'

Response (202 Accepted)

{
  "data": {
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "status": "completed",
    "engines": {
      "chat": { "status": "provisioned" },
      "voip": { "status": "provisioned" },
      "drive": { "status": "provisioned" },
      "mail": { "status": "provisioned" },
      "activity": { "status": "provisioned" },
      "usermanager": { "status": "provisioned" }
    }
  }
}

Response (partial failure)

{
  "data": {
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "status": "partial_failure",
    "engines": {
      "chat": { "status": "provisioned" },
      "voip": { "status": "failed", "error": "Connection refused" },
      "drive": { "status": "provisioned" },
      "mail": { "status": "provisioned" },
      "activity": { "status": "provisioned" },
      "usermanager": { "status": "provisioned" }
    }
  }
}

POST/core/api/internal/orchestration/provision/user

Provision user

Trigger user provisioning across all registered engines. This creates the user's presence in each engine (e.g., Matrix user in chat, SIP extension in VoIP, storage quota in drive).

Required attributes

Name
tenant_id
Type
string (UUID)
Description
The UUID of the tenant the user belongs to.
Name
tenant_short_id
Type
string
Description
The short slug identifier for the tenant.
Name
user_id
Type
string (UUID)
Description
The UUID of the user to provision.
Name
email
Type
string
Description
The user's email address.
Name
first_name
Type
string
Description
The user's first name.
Name
last_name
Type
string
Description
The user's last name.
Name
type
Type
string
Description
The user type: user, guest, or agent.

Request

POST

/core/api/internal/orchestration/provision/user

curl -X POST http://core:7002/api/internal/orchestration/provision/user \
  -H "Content-Type: application/json" \
  -H "X-Sphere-Signature: t=1708800000,v1=abc123..." \
  -d '{
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "tenant_short_id": "acme",
    "user_id": "a7c8e9f0-1234-5678-abcd-ef0123456789",
    "email": "alice@acme.local",
    "first_name": "Alice",
    "last_name": "Martin",
    "type": "user"
  }'

Response (202 Accepted)

{
  "data": {
    "user_id": "a7c8e9f0-1234-5678-abcd-ef0123456789",
    "status": "completed",
    "engines": {
      "chat": { "status": "provisioned" },
      "voip": { "status": "provisioned" },
      "drive": { "status": "provisioned" },
      "mail": { "status": "provisioned" },
      "activity": { "status": "provisioned" },
      "usermanager": { "status": "provisioned" }
    }
  }
}

POST/core/api/internal/orchestration/deprovision/user

Deprovision user

Trigger user deprovisioning across all registered engines. This removes the user's presence from each engine.

Required attributes

Name
tenant_id
Type
string (UUID)
Description
The UUID of the tenant the user belongs to.
Name
user_id
Type
string (UUID)
Description
The UUID of the user to deprovision.

Request

POST

/core/api/internal/orchestration/deprovision/user

curl -X POST http://core:7002/api/internal/orchestration/deprovision/user \
  -H "Content-Type: application/json" \
  -H "X-Sphere-Signature: t=1708800000,v1=abc123..." \
  -d '{
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "user_id": "a7c8e9f0-1234-5678-abcd-ef0123456789"
  }'

Response (202 Accepted)

{
  "data": {
    "user_id": "a7c8e9f0-1234-5678-abcd-ef0123456789",
    "status": "completed"
  }
}

POST/core/api/internal/orchestration/deprovision/tenant

Deprovision tenant

Trigger tenant deprovisioning across all registered engines. This removes all tenant data from each engine. This is a destructive operation.

Required attributes

Name
tenant_id
Type
string (UUID)
Description
The UUID of the tenant to deprovision.

Request

POST

/core/api/internal/orchestration/deprovision/tenant

curl -X POST http://core:7002/api/internal/orchestration/deprovision/tenant \
  -H "Content-Type: application/json" \
  -H "X-Sphere-Signature: t=1708800000,v1=abc123..." \
  -d '{
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
  }'

Response (202 Accepted)

{
  "data": {
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "status": "completed"
  }
}

GET/core/api/internal/orchestration/provision/tenant/{tenantId}/status

Check tenant provision status

Check the current provisioning status of a tenant across all engines. Use this to monitor whether all engines have been successfully provisioned or to identify which engines failed.

Request

GET

/core/api/internal/orchestration/provision/tenant/{tenantId}/status

curl http://core:7002/api/internal/orchestration/provision/tenant/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/status \
  -H "X-Sphere-Signature: t=1708800000,v1=abc123..."

Response

{
  "data": {
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "status": "partial_failure",
    "engines": {
      "chat": { "status": "provisioned", "provisioned_at": "2026-01-15T10:30:01Z" },
      "voip": { "status": "failed", "error": "Connection refused", "failed_at": "2026-01-15T10:30:05Z" },
      "drive": { "status": "provisioned", "provisioned_at": "2026-01-15T10:30:02Z" },
      "mail": { "status": "provisioned", "provisioned_at": "2026-01-15T10:30:03Z" },
      "activity": { "status": "provisioned", "provisioned_at": "2026-01-15T10:30:04Z" },
      "usermanager": { "status": "provisioned", "provisioned_at": "2026-01-15T10:30:06Z" }
    }
  }
}

POST/core/api/internal/orchestration/provision/tenant/{tenantId}/retry

Retry failed provisions

Retry provisioning for engines that failed during the initial tenant provisioning. Only engines with a failed status will be retried. This endpoint accepts no request body.

Request

POST

/core/api/internal/orchestration/provision/tenant/{tenantId}/retry

curl -X POST http://core:7002/api/internal/orchestration/provision/tenant/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/retry \
  -H "X-Sphere-Signature: t=1708800000,v1=abc123..."

Response (202 Accepted)

{
  "data": {
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "status": "completed",
    "retried_engines": ["voip"],
    "engines": {
      "voip": { "status": "provisioned", "provisioned_at": "2026-01-15T11:00:02Z" }
    }
  }
}

POST/api/internal/{engine}/provision/tenant

Individual engine provision (tenant)

Each engine exposes its own internal provision endpoint that sphere-core calls during orchestration. These endpoints are called sequentially by the orchestrator and should not be called directly unless debugging.

The endpoint path follows the pattern /api/internal/{engine}/provision/tenant where {engine} is the engine code (e.g., voip, chat, drive).

Required attributes

Name
tenant_id
Type
string (UUID)
Description
The UUID of the tenant to provision.
Name
tenant_short_id
Type
string
Description
The short slug identifier for the tenant.
Name
name
Type
string
Description
The display name of the tenant.

Request

POST

/api/internal/voip/provision/tenant

curl -X POST http://voip:7007/api/internal/voip/provision/tenant \
  -H "Content-Type: application/json" \
  -H "X-Sphere-Signature: t=1708800000,v1=abc123..." \
  -d '{
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "tenant_short_id": "acme",
    "name": "Acme Corp"
  }'

Response (200 OK)

{
  "data": {
    "status": "provisioned",
    "engine": "voip"
  }
}

POST/api/internal/{engine}/deprovision/tenant

Individual engine deprovision (tenant)

Each engine exposes its own internal deprovision endpoint for removing tenant data. Called by sphere-core during tenant deprovisioning orchestration.

Required attributes

Name
tenant_id
Type
string (UUID)
Description
The UUID of the tenant to deprovision.

Request

POST

/api/internal/chat/deprovision/tenant

curl -X POST http://chat:7006/api/internal/chat/deprovision/tenant \
  -H "Content-Type: application/json" \
  -H "X-Sphere-Signature: t=1708800000,v1=abc123..." \
  -d '{
    "tenant_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
  }'

Response (200 OK)

{
  "data": {
    "status": "deprovisioned",
    "engine": "chat"
  }
}