REST API and Tokens

The REST API lets an external system talk to agents and access the resources published by the organization’s API. It does not reproduce the entire admin panel: the current surface covers chat, agents, conversations, knowledge bases, tags, and contact lists.

Each token belongs to the organization selected when it is created and authorizes the entire public API surface for that organization. Current tokens do not have per-endpoint scopes; treat each one as a privileged credential.

Open API settings

1. Open Settings from your avatar menu.
2. Under Developers, select API.
3. Use Tokens to manage credentials or Documentation to open the technical reference.

The direct address is /settings/api.

Permissions

Access is divided into three capabilities confirmed in the interface:

• View API tokens: open the section and list names, prefixes, and usage;
• Create and rotate API tokens: generate and revoke tokens;
• Delete API tokens: permanently remove a record.

Administrators receive these capabilities by default. A custom role can receive them separately, so the ability to generate tokens does not depend only on the role name.

Generate a token

1. In API → Tokens, click Generate API Token.
2. In Generate API Token, enter a Token Name that identifies the integration, such as n8n production or internal backend.
3. Click Generate Token.
4. In Token Generated, copy the value and immediately store it in a secrets vault or server environment variable.

The token starts with pk_ and contains 64 hexadecimal characters after the prefix. SquadOS displays the full value only once and stores only its hash. Closing the dialog ends the only opportunity to copy that credential; if it is lost, generate another one and revoke the old token.

Understand the table

The Tokens tab shows:

• Name and Prefix, which identify a credential without revealing its secret;
• Status: Active or Revoked;
• Created at and Last used;
• Calls, incremented when a request authenticates the token;
• Actions, according to your permissions.

The full value never returns to the table. The displayed prefix is pk_ plus the first eight secret characters, followed by an ellipsis.

Revoke or delete

• Revoke token immediately disables the credential while keeping its name, prefix, and history in the table. A revoked token cannot be reactivated.
• Delete token permanently removes the record. The interface asks for confirmation because this action is irreversible.

If you suspect a leak, revoke first to stop requests. Delete only when you no longer need the record for auditing.

Use the token

The public base URL is:

https://api.squados.io/v1

Send the token as a Bearer credential on every request:

Authorization: Bearer pk_your_token_here

Example that lists the organization’s agents:

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

Synchronous message example:

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}'

A missing, malformed, invalid, or revoked token receives 401 with the unauthorized code. Tokens do not have an automatic expiration date in the current interface.

Available resources

See the API Overview for the base URL, formats, and current catalog. The reference is divided into:

• Chat;
• Conversations;
• Agents;
• Knowledge Bases;
• Tags;
• Contact Lists;
• Webhooks and Errors.

The Documentation settings tab opens this reference. To execute calls in the browser, use the interactive Swagger linked from the API Overview.

Protection and rotation

• Generate a different token for each integration and environment so you can revoke one consumer without interrupting the others.
• Never send tokens to a browser, mobile app, repository, log, conversation, or agent prompt.
• Store them only on the server, in a secrets manager.
• Compare Last used and Calls before retiring a credential.
• To rotate, generate the new token, update the consumer, confirm one request, and only then revoke the old token.

English interface

Titles and controls are translated, but success and error notifications for token creation, revocation, and deletion still appear in Portuguese. This is a known product limitation, not a change in token state.