Operator control plane

Create a room

Registers tenant_id (1–128 characters) as a tenant if it is new. With external_ref the call is idempotent per tenant: repeating it returns the existing room unchanged and ignores the other fields. Without external_ref, every call creates a new room. The room has no members. e2ee and e2ee_scheme (mls or megolm, which requires e2ee: true) are set at creation and cannot change. expires_at is informational only: nothing closes or deletes the room when it passes.

createRoom captured live

Request

curl -X POST https://api.ollacore.com/internal/v1/rooms \
  -H "X-Chatbox-Key-Id: $KEY_ID" \
  -H "X-Chatbox-Timestamp: $TS" \
  -H "X-Chatbox-Nonce: $NONCE" \
  -H "X-Chatbox-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id":"acct_fac91b282191cc02dd29912c8db43f1c","created_by":"alice","external_ref":"ops-room-1"}'

{
  "tenant_id": "acct_fac91b282191cc02dd29912c8db43f1c",
  "created_by": "alice",
  "external_ref": "ops-room-1"
}

Request fields

Response · 200

{
  "id": "00919f0a-cfeb-438d-bdb7-65af28b4f678",
  "tenant_id": "acct_fac91b282191cc02dd29912c8db43f1c",
  "external_ref": "ops-room-1",
  "created_by": "alice",
  "status": "active",
  "e2ee": false,
  "created_at": "2026-01-15T09:30:02Z"
}

Resolve by external_ref

Both tenant_id and external_ref are required, and external_ref must match exactly within that tenant. The room is returned whatever its status.

lookupRoom captured live

Request

curl -X GET https://api.ollacore.com/internal/v1/rooms?tenant_id=acct_fac91b282191cc02dd29912c8db43f1c&external_ref=ops-room-1 \
  -H "X-Chatbox-Key-Id: $KEY_ID" \
  -H "X-Chatbox-Timestamp: $TS" \
  -H "X-Chatbox-Nonce: $NONCE" \
  -H "X-Chatbox-Signature: $SIG"

Response · 200

{
  "id": "00919f0a-cfeb-438d-bdb7-65af28b4f678",
  "tenant_id": "acct_fac91b282191cc02dd29912c8db43f1c",
  "external_ref": "ops-room-1",
  "created_by": "alice",
  "status": "active",
  "e2ee": false,
  "created_at": "2026-01-15T09:30:02Z"
}

Patch status / expiry

Leave a field out to keep its current value. expires_at cannot be cleared, because null also keeps the current value. status must be active or closed (400 otherwise). Closing a room only stops new session tokens from being minted for it (409 room is closed). Members keep their tokens, open sockets and history, and can still send until their tokens expire. Setting active lifts this. No event is published. expires_at remains informational only.

patchRoom captured live

Request

curl -X PATCH https://api.ollacore.com/internal/v1/rooms/00919f0a-cfeb-438d-bdb7-65af28b4f678 \
  -H "X-Chatbox-Key-Id: $KEY_ID" \
  -H "X-Chatbox-Timestamp: $TS" \
  -H "X-Chatbox-Nonce: $NONCE" \
  -H "X-Chatbox-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{"expires_at":"2026-01-16T09:30:02Z"}'

{
  "expires_at": "2026-01-16T09:30:02Z"
}

Request fields

Response · 200

{
  "id": "00919f0a-cfeb-438d-bdb7-65af28b4f678",
  "tenant_id": "acct_fac91b282191cc02dd29912c8db43f1c",
  "external_ref": "ops-room-1",
  "created_by": "alice",
  "status": "active",
  "e2ee": false,
  "created_at": "2026-01-15T09:30:02Z",
  "expires_at": "2026-01-16T09:30:02Z"
}

Members, presence, live call roster

member_count counts active members. online_participants lists the members who currently have chat presence. rtc_participants lists the principals in the room's call on the SFU at request time, and is empty when nobody is in the call. If presence cannot be read, online_participants comes back empty and the request still succeeds.

roomStatus captured live

Request

curl -X GET https://api.ollacore.com/internal/v1/rooms/25964f12-9ae9-4356-80e8-69bc5f749bd1/status \
  -H "X-Chatbox-Key-Id: $KEY_ID" \
  -H "X-Chatbox-Timestamp: $TS" \
  -H "X-Chatbox-Nonce: $NONCE" \
  -H "X-Chatbox-Signature: $SIG"

Response · 200

{
  "room": {
    "id": "25964f12-9ae9-4356-80e8-69bc5f749bd1",
    "tenant_id": "acct_fac91b282191cc02dd29912c8db43f1c",
    "external_ref": "order-7781",
    "created_by": "alice",
    "status": "active",
    "e2ee": false,
    "created_at": "2026-01-15T09:30:03Z"
  },
  "member_count": 4,
  "online_participants": [],
  "rtc_participants": []
}

Add a member

A room holds at most 5,000 active members, on every plane; once it is full the add is refused with 409 and nothing changes. Restoring a removed member or changing an existing member's role never needs a seat.

addMember captured live

Request

curl -X POST https://api.ollacore.com/internal/v1/rooms/00919f0a-cfeb-438d-bdb7-65af28b4f678/members \
  -H "X-Chatbox-Key-Id: $KEY_ID" \
  -H "X-Chatbox-Timestamp: $TS" \
  -H "X-Chatbox-Nonce: $NONCE" \
  -H "X-Chatbox-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{"principal_id":"alice","role":"owner"}'

{
  "principal_id": "alice",
  "role": "owner"
}

Request fields

Response · 200

{
  "tenant_id": "acct_fac91b282191cc02dd29912c8db43f1c",
  "room_id": "00919f0a-cfeb-438d-bdb7-65af28b4f678",
  "principal_id": "alice",
  "role": "owner",
  "joined_at": "2026-01-15T09:30:02Z"
}

Remove a member

Sets the membership's left_at; history is kept, and adding the principal again restores the membership. The removal takes effect at once: the member's live chat and RTC sockets close with 4403, and their HTTP requests and new session tokens are refused. A durable member.removed event goes to the room's connected clients and to webhooks subscribed to it. E2EE clients use this event as the cue to rotate keys. 404 if the room does not exist or the principal is not an active member.

removeMember captured live

Request

curl -X DELETE https://api.ollacore.com/internal/v1/rooms/00919f0a-cfeb-438d-bdb7-65af28b4f678/members/carol2 \
  -H "X-Chatbox-Key-Id: $KEY_ID" \
  -H "X-Chatbox-Timestamp: $TS" \
  -H "X-Chatbox-Nonce: $NONCE" \
  -H "X-Chatbox-Signature: $SIG"

Response · 200

{
  "removed": true
}

Mint a token

role defaults to the member's stored role and may only lower it: a token above the member's role (viewer → owner) is refused with 403, a role outside owner|member|viewer with 400.

mintSessionToken captured live

Request

curl -X POST https://api.ollacore.com/internal/v1/session-tokens \
  -H "X-Chatbox-Key-Id: $KEY_ID" \
  -H "X-Chatbox-Timestamp: $TS" \
  -H "X-Chatbox-Nonce: $NONCE" \
  -H "X-Chatbox-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id":"acct_fac91b282191cc02dd29912c8db43f1c","room_id":"00919f0a-cfeb-438d-bdb7-65af28b4f678","principal_id":"alice","role":"owner","ttl_seconds":3600}'

{
  "tenant_id": "acct_fac91b282191cc02dd29912c8db43f1c",
  "room_id": "00919f0a-cfeb-438d-bdb7-65af28b4f678",
  "principal_id": "alice",
  "role": "owner",
  "ttl_seconds": 3600
}

Request fields

Response · 200

{
  "access_token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6ImEwM2I1NjQ4MjM3YjlmZWIifQ.eyJpc3MiOiJjaGF0Ym94LWJhY2tlbmQiLCJhdWQiOiJjaGF0Ym94LXJlYWx0aW1lIiwic3ViIjoiYWxpY2UiLCJ0aWQiOiJhY2N0X2ZhYzkxYjI4MjE5MWNjMDJkZDI5OTEyYzhkYjQzZjFjIiwicmlkIjoiMDA5MTlmMGEtY2ZlYi00MzhkLWJkYjctNjVhZjI4YjRmNjc4Iiwicm9sZSI6Im93bmVyIiwicGVybWlzc2lvbnMiOlsiY2hhdDpzZW5kIiwiY2hhdDpoaXN0b3J5IiwiYXR0YWNobWVudDp1cGxvYWQiLCJhdHRhY2htZW50OmRvd25sb2FkIiwicnRjOnB1Ymxpc2giLCJydGM6c3Vic2NyaWJlIl0sImp0aSI6ImJmZThlYzg2LTVkZmUtNDM1YS1iNTk3LTkwZjBkY2RhM2FiZSIsImlhdCI6MTc5MjMyNDY2NSwibmJmIjoxNzkyMzI0NjY1LCJleHAiOjE3OTIzMjgyNjV9.SIGNATURE_REMOVED",
  "expires_at": "2026-01-15T10:30:02Z",
  "rtc_websocket_url": "wss://api.ollacore.com/v1/rtc/ws",
  "chat_websocket_url": "wss://api.ollacore.com/v1/chat/ws",
  "ice_servers": [
    {
      "urls": [
        "stun:api.ollacore.com:3478"
      ]
    },
    {
      "urls": [
        "turn:api.ollacore.com:3478",
        "turns:api.ollacore.com:5349"
      ],
      "username": "1789064267:alice",
      "credential": "EXAMPLE_TURN_CREDENTIAL="
    }
  ]
}

Per-room unread for a principal

tenant_id is required. Lists every room where the principal is an active member, including rooms with no unread messages. A room's count is the messages after the principal's read cursor, excluding their own and deleted messages, and total is the sum. A principal with no memberships gets total: 0 and an empty list.

principalUnread captured live

Request

curl -X GET https://api.ollacore.com/internal/v1/principals/bob/unread?tenant_id=acct_fac91b282191cc02dd29912c8db43f1c \
  -H "X-Chatbox-Key-Id: $KEY_ID" \
  -H "X-Chatbox-Timestamp: $TS" \
  -H "X-Chatbox-Nonce: $NONCE" \
  -H "X-Chatbox-Signature: $SIG"

Response · 200

{
  "rooms": [
    {
      "room_id": "25964f12-9ae9-4356-80e8-69bc5f749bd1",
      "unread_count": 0
    }
  ],
  "total": 0
}

Issue a customer key

environment is live or test. A test key works in a separate {tenant_id}::test sandbox with its own rooms, messages and usage, so tenant_id may not contain ::. Each scope must be one of rooms:read, rooms:write, members:write, tokens:mint, messages:write, webhooks:manage, usage:read, rooms:delete or data:erase. plan defaults to default and must already exist. Any invalid value is 400. The tenant, and for a test key its sandbox, is registered if new. api_key (ak_<env>_<id>.<secret>) is returned only once, because the server stores only a SHA-256 digest of the secret. After expires_at the key is refused with 401.

createApiKey captured live

Request

curl -X POST https://api.ollacore.com/internal/v1/api-keys \
  -H "X-Chatbox-Key-Id: $KEY_ID" \
  -H "X-Chatbox-Timestamp: $TS" \
  -H "X-Chatbox-Nonce: $NONCE" \
  -H "X-Chatbox-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id":"acct_fac91b282191cc02dd29912c8db43f1c","name":"sandbox-key","environment":"test","scopes":["rooms:read","rooms:write"]}'

{
  "tenant_id": "acct_fac91b282191cc02dd29912c8db43f1c",
  "name": "sandbox-key",
  "environment": "test",
  "scopes": [
    "rooms:read",
    "rooms:write"
  ]
}

Request fields

Response · 200

{
  "key_id": "key-id-sandbox",
  "api_key": "ak_live_EXAMPLE.NOT_A_REAL_KEY",
  "tenant_id": "acct_fac91b282191cc02dd29912c8db43f1c",
  "environment": "test",
  "scopes": [
    "rooms:read",
    "rooms:write"
  ]
}

Revoke a key

Takes effect on the key's next request, which is refused with 401. 404 if the id is unknown or the key is already revoked. Session tokens the key already minted stay valid until they expire, at most one hour. After revocation the key's plan no longer counts toward the tenant's quotas or retention window.

revokeApiKey captured live

Request

curl -X DELETE https://api.ollacore.com/internal/v1/api-keys/key-id-sandbox \
  -H "X-Chatbox-Key-Id: $KEY_ID" \
  -H "X-Chatbox-Timestamp: $TS" \
  -H "X-Chatbox-Nonce: $NONCE" \
  -H "X-Chatbox-Signature: $SIG"

Response · 200

{
  "revoked": true
}

Create/update a rate + quota plan

Replaces the whole plan. Optional fields left out become null: unlimited quota, no plan retention, no description. name is 1–64 characters, rate_limit and rate_window_seconds must be positive, and quotas and retention_days must be at least 0 or null; anything else is 400. Plans are global. The rate limit applies per key, from that key's next request. For each quota and for retention, a tenant gets the most generous plan among its live keys, and null counts as unlimited. A tenant's own retention setting overrides the plan's. Monthly quotas count message.sent and attachment.bytes per UTC calendar month.

putPlan captured on a test deployment

Request

curl -X PUT https://api.ollacore.com/internal/v1/plans/docs-example \
  -H "X-Chatbox-Key-Id: $KEY_ID" \
  -H "X-Chatbox-Timestamp: $TS" \
  -H "X-Chatbox-Nonce: $NONCE" \
  -H "X-Chatbox-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{"rate_limit":120,"rate_window_seconds":10,"monthly_message_quota":5000000,"monthly_byte_quota":549755813888,"retention_days":365,"description":"Example tier for documentation"}'

{
  "rate_limit": 120,
  "rate_window_seconds": 10,
  "monthly_message_quota": 5000000,
  "monthly_byte_quota": 549755813888,
  "retention_days": 365,
  "description": "Example tier for documentation"
}

Request fields

Response · 200

{
  "plan": "docs-example"
}

Offboard a tenant — revokes the account and its logins, keys and directory at once, then erases rooms, blobs, webhooks and usage

Async, in two steps. At once, every way in is revoked: the tenant's account (and its sessions), API keys, directory apps, pending OTP challenges and directory sessions. About 45 seconds later — long enough for any request already in flight to finish — every room is purged (blobs, rows and every stored copy of its events), then the rest of the tenant's data: usage ledger, webhooks and their delivery log, push subscriptions, identities, the directory, and E2EE key material. Most destructive; HMAC-only.

purgeTenant captured live

Request

curl -X DELETE https://api.ollacore.com/internal/v1/tenants/acct_fac91b282191cc02dd29912c8db43f1c \
  -H "X-Chatbox-Key-Id: $KEY_ID" \
  -H "X-Chatbox-Timestamp: $TS" \
  -H "X-Chatbox-Nonce: $NONCE" \
  -H "X-Chatbox-Signature: $SIG"

Response · 200

{
  "purging": true
}