Platform API (multi-account provisioning)

Open in

View as Markdown

Open in ChatGPT Open in Claude

Conversa Labs

Last updated on Sep 5, 2026

Overview

The Platform API operates above accounts: it lets you create and manage accounts, users, user-account memberships and agent bots programmatically. Everything lives under a Platform App — a platform application that the operator creates and that gets its own token.

Difference from the account REST API:

The REST API works inside a single account (contacts, conversations, messages) and uses the token of a user/agent in that account.
The Platform API works across accounts (provisioning and lifecycle) and uses the Platform App token. Its endpoints live under the /platform/api/v1 prefix.

A Platform App only sees and changes the objects in its permissible list (the accounts, users and bots it created or that were associated with it).

Prerequisites

A Platform App created by the operator (Super Admin -> Platform Apps).
The access token of that Platform App (generated together with the app).
The token must travel on the operator backend only — never in the front-end.

Step by step

The operator creates a Platform App in Super Admin -> Platform Apps. On save, the platform generates an access token bound to the app.
Authenticate every call by sending the api_access_token header with the Platform App token. If the token does not belong to a Platform App, the response is 401 Invalid access_token.

Create an account:

POST /platform/api/v1/accounts
api_access_token: <platform-token>
Content-Type: application/json

{ "name": "Acme Co", "locale": "en", "support_email": "support@acme.com" }

The new account is automatically added to the app's permissibles.

Create a user:
```
POST /platform/api/v1/users
{ "name": "Mary", "email": "mary@acme.com", "password": "<strong-password>" }
```
The user also enters the app's permissibles. If a user with that e-mail already exists, the platform reuses the existing user.

Link user and account (account_user) with a role:

POST /platform/api/v1/accounts/<account_id>/account_users
{ "user_id": <user_id>, "role": "administrator" }

Use administrator or agent in the role field.

Provision agent bots:

POST /platform/api/v1/agent_bots
{ "name": "Sales Bot", "account_id": <account_id>, "outgoing_url": "https://my-bot/webhook", "receive_incoming_when_assigned": false }

Complementary endpoints: GET/PATCH/DELETE /platform/api/v1/accounts/:id, GET :id and DELETE :id for users, GET .../account_users (list), DELETE .../account_users (remove membership), GET :id/login (generates an SSO login link for the user) and POST :id/token.

Settings & options

Permissible objects: each Platform App keeps a list of accounts, users and agent bots it can manage. Objects the app creates enter that list automatically.
Token scope: the Platform App token only acts on the app's permissibles — it does not reach accounts/users of other apps nor a single account's internal data (use the account REST API for that).
Account parameters: name, locale, domain, support_email, status, plus features, limits and custom_attributes.
User parameters: name, display_name, email, password and custom_attributes.
Agent-bot delivery during assignment: receive_incoming_when_assigned defaults to false. Enable it only for external bots that must retain messages during human handling. It applies to every linked inbox, and the integrator remains responsible for not replying over the agent.

Use cases

Multi-tenant onboarding / reseller: create one account per customer and seed users in bulk.
SSO-style provisioning: create the user and generate the login link (GET :id/login) to take the user straight to the dashboard with no manual password.
Automated lifecycle: create, update and deactivate accounts and memberships from your own system (for example, when a subscription is completed or canceled).

Tips, limits & best practices

Keep the Platform App token on the operator backend only. It has provisioning power — never expose it in the front-end or in client apps.
Work with tight permissions: the app should only touch the objects it created.
Account and user deletion is asynchronous (queued) — a 200 response means the deletion was scheduled, not finished in the same instant.
Handle idempotency: creating a user with an existing e-mail reuses the record; creating the same account-user membership does not duplicate it.

Troubleshooting

401 Invalid access_token: the token does not belong to a Platform App (or is missing/incorrect in the api_access_token header).
401 Non permissible resource: the object (account/user/bot) is not in the app's permissible list — you are trying to change something the app does not manage.
404: the supplied id does not exist.