Conversa Labs Help Center
en
Language
pt_BR Portuguese (Brazil) en English es Spanish

Platform API (multi-account provisioning)

Open in
View as Markdown Open in ChatGPT Open in Claude
Conversa Labs

Conversa Labs

Last updated on Jul 16, 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

  1. The operator creates a Platform App in Super Admin -> Platform Apps. On save, the platform generates an access token bound to the app.

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

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

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

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

  6. Provision agent bots:

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

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.

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.

See also