Authentication

Every API call uses an API token in the Authorization header, Bearer style. The token starts with pk_, belongs to one organization, and what it can reach depends on the scope chosen when it was generated.

Authorization: Bearer pk_your_token_here

Scopes

When generating the token, you choose under What this token can do:

• Full access — uses the organization’s entire public API: chat, conversations, contacts, lists, agents, knowledge bases, tags, metrics and email sending.
• Send emails only — only sends and reads emails (Emails), and only from the senders checked under Allowed senders. Any other endpoint returns 403 forbidden with reason: "token_scope_email_only".

The scope is set at creation, and the interface does not let you change it later. To switch, generate another token and revoke the old one. The tokens table shows the scope under the name: Full access or Email only, with the number of senders.

Caution

A Full access token acts as the whole organization on the API. Treat each token as a privileged password: keep it server-side and never expose it in a frontend, mobile app, repository, log, conversation, or prompt. When the integration only sends email, prefer Send emails only.

Generate a token

You need Create and rotate API tokens. Administrators receive this capability by default, and custom roles can receive it separately.

1. Open Settings from the avatar menu and select Developers → API. The direct address is /settings/api.

2. In Tokens, click Generate API Token.

3. Enter a Token Name, such as n8n production or internal backend.

4. Under What this token can do, choose Full access or Send emails only. For Send emails only, check at least one sender under Allowed senders; the list shows the senders registered under Settings → Email and flags those whose domain is not verified yet.

5. Click Generate Token.

6. In Token Generated, copy the value immediately. It is displayed only once; SquadOS stores only its hash and prefix.

If you close the dialog or lose the value, it cannot be recovered. Generate another token, update the integration, and revoke the old one.

Use the token

The production base URL is https://api.squados.io/v1. Include the header on every request and use Content-Type: application/json when the request has a body:

curl https://api.squados.io/v1/agents \
  -H "Authorization: Bearer pk_your_token_here"

curl -X POST https://api.squados.io/v1/chat/AGENT_ID \
  -H "Authorization: Bearer pk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello!","sync":true}'

The token determines the organization for the request. IDs from another organization are not accessible with that credential.

Manage tokens

The API → Tokens table shows name, prefix, status, creation, last use, and call count. The complete secret value never appears again.

• View API tokens lets you open and inspect the table.
• Create and rotate API tokens lets you generate and revoke.
• Delete API tokens lets you permanently remove a record.

Revoke token stops authentication and keeps the row as Revoked. Delete token removes the row after confirmation. Revoked tokens cannot be reactivated.

Tip

Use one token per integration and environment. To rotate without interruption, generate the new token, replace the consumer secret, confirm one request, and only then revoke the old one.

Authentication errors

A missing, malformed, invalid, or revoked token returns 401:

{
  "error": "Invalid or missing API token",
  "code": "unauthorized"
}

Check the space after Bearer, the pk_ prefix, and whether the token is still Active. The current interface does not configure automatic expiration. See Errors for the full contract.

English interface

Notifications for creation, revocation, and deletion still appear in Portuguese even when the interface is in English. This does not change the operation result.