Authentication

Every call to the SquadOS API is authenticated with an API token sent in the Authorization header, Bearer style. The token is prefixed with pk_ and is scoped to your organization — it grants access to that organization’s agents, conversations, and bases.

Authorization: Bearer pk_your_key_here

Generating a token

Tokens are generated in the admin panel, under Settings → API.

1. In the admin panel, open Settings and select the API tab.

2. Click Generate API Token and give the token a name (e.g. n8n production, internal backend) so you can identify it later.

3. Copy the token right away. It is shown only once, right after creation. For security, SquadOS stores only a hash — there’s no way to retrieve the full value later. If you lose it, generate a new one.

Caution

The token grants full access to your organization’s resources via the API. Treat it like a password: keep it server-side, in an environment variable or secrets vault, and never expose it in the frontend, in public repositories, or in logs.

Using the token

Include the Authorization header on every request. On calls with a body, also send Content-Type: application/json:

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

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

Managing tokens

In the same API tab, the table lists every token in the organization:

• Prefix — the first characters of the token (e.g. pk_2d3d0e63...), so you can tell them apart without seeing the full value.
• Status — Active or Revoked.
• Created and Last used — when it was generated and last used.
• Calls — how many requests it has made.

Each token has two actions:

• Revoke — disables the token immediately. Calls with it start returning 401. The record stays in the table (marked revoked) for auditing.
• Delete — removes the token from the table for good.

Tip

Use one token per integration (one for n8n, another for your backend, etc.). That way you revoke only what leaked or was retired, without breaking the other integrations, and the Calls column shows each one’s usage separately.

Authentication errors

When the token is missing, malformed, revoked, or invalid, the API responds 401:

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

Check that the header is in the exact form Authorization: Bearer pk_... (with the space after Bearer) and that the token hasn’t been revoked. See Errors for the full list of codes.