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.
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;
trueby 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
}
apiKeyis 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 excludeevents: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
externalIdagain answers with that sub-account, active again if it was deactivated, its name unchanged. Each call issues another key, unlessissueKeyisfalse, 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.
List sub-accounts
Every sub-account, the deactivated ones too, active false, in the order they were created. The list never carries keys.
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
externalIdwith no active sub-account is404 ACCOUNT_NOT_FOUND. - Its webhook events go to its own endpoints if it has any, and otherwise to yours, with its
externalIdin each event'saccount. See Webhooks. - SMS templates a sub-account sends are those you share with it. See Templates.