Tokens and authentication in the Developer API

Last updated: 11 November 2026 · 7 min read

Steps

1. 1

   Address and headers

   • Base URL (the start of every address): https://api.clomni.ai/v1, HTTPS only.
   • Token header: Authorization: Bearer <token>.
   • When you send a body: Content-Type: application/json, UTF-8. The response is JSON.
   • Error text is in Azerbaijani by default and in English with Accept-Language: en.

   The address has no workspace number: GET /v1/conversations returns the conversations in the token's workspace. An action made through the API appears under the token owner's name: the app owner for an internal app, and the administrator who connected the app for a public app.

2. 2

   Token types

   • Personal access token (clomni_pat_): created in the portal, 30, 60, 90, 180 or 365 days (default 90). For scripts, tests and small internal jobs.
   • App token (clomni_at_): your server gets it itself with client_id and client_secret, and it works for 1 hour. For a server integration that runs all the time.
   • OAuth access token (clomni_at_, 1 hour) and refresh token (clomni_rt_, 90 days): for each installation of a public app. See the “Public app and OAuth” article.
   • Client secret (clomni_secret_) and webhook secret (whsec_): created in the portal and shown only once.

   Clomni stores tokens only as hashes, so it cannot show a token a second time. If you lose one, create a new one and revoke the old one.

3. 3

   Create a personal access token

   Open the app in the portal and press “Create token” in the “Credentials” section. Choose a name (up to 60 characters), scopes and a lifetime. You can choose only approved scopes. messages:send and conversations:write can be chosen before review too, but until approval they work only on the test channel. An app can have at most 10 active personal access tokens at a time. A public app has no personal access tokens.

4. 4

   Get an app token (client credentials)

   The “Credentials” section shows the client_id (it starts with capp_). Get clomni_secret_... with “Create secret”. When you create the secret again, the old one keeps working for 7 more days. The token request:

   curl -X POST https://api.clomni.ai/v1/oauth/token \
     -u "$CLOMNI_CLIENT_ID:$CLOMNI_CLIENT_SECRET" \
     -d grant_type=client_credentials \
     -d scope="conversations:read messages:read"

   The response has access_token (clomni_at_...), expires_in: 3600, scope and workspace_id. If scope is left out, all approved scopes are granted. Keep the token in memory until it expires and reuse it: /oauth/token is limited to 20 requests a minute. There is no refresh token: when the token expires, send the same request. Errors: invalid_client (401, the client details are wrong), unauthorized_client (the app is suspended or archived, its owner is not an administrator, or it has no approved scope), invalid_scope, unsupported_grant_type.

5. 5

   Check the token: GET /me

   GET /v1/me returns who the token belongs to and which scopes work. It needs no scope:

   curl https://api.clomni.ai/v1/me \
     -H "Authorization: Bearer clomni_pat_xxx"

   The response has app, workspace, user, token (kind, expires_at, scopes) and scopes. token.scopes are the scopes written on the token, and scopes are the ones that work now: a scope that was removed from the app or is not approved is not there.

6. 6

   When a token stops on its own

   • When it expires: 401 token_expired or invalid_token.
   • When the app owner changes their password.
   • When Clomni suspends the app (403 app_suspended) or the app is archived.
   • When the app owner is not an administrator in the workspace: 403 app_owner_not_admin. It works again once the role is given back.
   • When the workspace is suspended: 403 account_suspended, and only workspace:read works.

   Revoke a personal access token in the portal: revoking takes effect at once. Revoke an app token with POST /v1/oauth/revoke.

7. 7

   Keep tokens safe

   Keep tokens and secrets only on your server: never in browser code, a mobile app, a public repository or logs. Create a separate token for each environment, and write only the last 4 characters of a token to logs. If you think a token has leaked, revoke it or rotate the secret right away, then write to [email protected].