## 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

- [REST API, tokens and webhooks](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-en)
- [API Reference (Swagger / OpenAPI)](/hc/ajuda/articles/api-developers-swagger-reference-en)
- [API & Developers overview](/hc/ajuda/articles/api-developers-overview-en)