Sub-accounts

A platform that sends for its own customers gives each one a sub-account: an Oblic organization of its own, with its own senders, templates, messages and reports, which your key acts for by naming it. Managing sub-accounts needs an Owner or Admin key that holds accounts:manage.


POST/external/v1/accounts

Create a sub-account

  • Name
    name
    Type
    string
    Description

    Required: the tenant's name, at most 511 characters.

  • Name
    externalId
    Type
    string
    Description

    Required: your own id for the tenant, at most 100 ASCII letters, digits, _, ., : and -. It is how you name the sub-account afterwards.

  • Name
    issueKey
    Type
    boolean
    Description

    Whether to issue the sub-account an API key of its own; true by default.

Create a sub-account

curl -X POST https://api.oblic.app/external/v1/accounts \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Asha Textiles", "externalId": "tenant-4821" }'

Response

{
  "status": "success",
  "data": {
    "id": "ORG000R7ZM4Q2VXH00",
    "name": "Asha Textiles",
    "externalId": "tenant-4821",
    "active": true,
    "createdAt": "2026-10-24T09:30:00Z",
    "apiKey": "obl_live_…"
  },
  "errors": null
}
  • apiKey is shown in this answer only: store it then, or create the sub-account again for another. It is a User key with the legacy default scopes, which exclude events:write: it sends, reads and manages identities and contact lists, but can't call the routes that need an Owner or Admin key.
  • The same externalId again answers with that sub-account, active again if it was deactivated, its name unchanged. Each call issues another key, unless issueKey is false, and the earlier keys keep working, but for those revoked when it was deactivated.
  • A sub-account has no sub-accounts: creating one while acting for a sub-account is 403 SUB_ACCOUNT_NOT_ALLOWED.

GET/external/v1/accounts

List sub-accounts

Every sub-account, the deactivated ones too, active false, in the order they were created. The list never carries keys.


DELETE/external/v1/accounts/{accountId}

Deactivate a sub-account

Deactivates the sub-account, by Oblic's id, not your externalId, and revokes all its keys at once. Creating it again with its externalId makes it active again. A sub-account the organization doesn't have is 404 ACCOUNT_NOT_FOUND.


Acting for a sub-account

Send X-Oblic-On-Behalf-Of with the sub-account's externalId, and the request runs as the sub-account's, as though made with its own key. Your one key does it for every tenant, so you never hold one per tenant.

Send from a tenant's account

curl -X POST https://api.oblic.app/external/v1/messages/email \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'X-Oblic-On-Behalf-Of: tenant-4821' \
  -H 'Content-Type: application/json' \
  -d '{ "from": "hello@ashatextiles.example", "to": ["asha@example.org"], "subject": "Welcome", "html": "<p>Welcome!</p>" }'
  • Its own: an email goes only from the sub-account's own identities; its messages, reports, templates and webhooks are its own; and its Idempotency-Keys are its own.
  • Yours: your organization's wallet pays for its messages, and your IP allowlist applies to the requests you make for it.
  • Your key's role applies, so manage a tenant's templates, webhooks or WhatsApp number with your own Owner or Admin key and the header.
  • An externalId with no active sub-account is 404 ACCOUNT_NOT_FOUND.
  • Its webhook events go to its own endpoints if it has any, and otherwise to yours, with its externalId in each event's account. See Webhooks.
  • SMS templates a sub-account sends are those you share with it. See Templates.
Was this page helpful?