Authentication

Every API call uses an API token in the Authorization header, Bearer style. The token starts with pk_, belongs to one organization, and grants access to the entire public API surface for that organization.

Authorization: Bearer pk_your_token_here

Generate a token

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

Open Settings from the avatar menu and select Developers → API. The direct address is /settings/api.
In Tokens, click Generate API Token.
Enter a Token Name, such as n8n production or internal backend, and click Generate Token.
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.

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.