Skip to main content
Every request to the Xobito API must include a bearer token. Each workspace has a single API token, generated and managed from the dashboard. There is no concept of multiple tokens, per-token names, ability subsets, monthly quotas, or expiry dates — your one token grants all configured abilities for the workspace.

​
Token format

A Xobito API token is a 64-character hexadecimal string with no prefix: 
<your_token>
Treat the token like a password. Anyone with it can call every API endpoint on your workspace. Store it in a secrets manager — never commit it to source control or expose it to client-side code.

​
Generating a token

1

Open API Management

In your dashboard, go to Settings → API Management.
2

Enable API access

Flip the Enable API Access toggle on. The first time you do this, a token is generated automatically.
3

Copy the token

The token is displayed in the API Token field. Copy it into your password manager or secrets vault immediately.
4

Save

Click Save to persist the change.

​
Using a token

Send the token in the Authorization header on every request: 
curl https://dash.xobito.com/api/v1/acme/contacts \
  -H "Authorization: Bearer <your_token>" \
  -H "Accept: application/json"

​
Abilities

A workspace token automatically grants every API ability Xobito ships. There is no UI to issue narrower tokens; abilities are managed server-side in module configuration. The full ability list (used for documentation and internal authorisation checks):
AbilityGrants
contacts.createCreate contacts
contacts.readList / read contacts
contacts.updateUpdate contacts
contacts.deleteDelete contacts
statuses.createCreate contact statuses
statuses.readList / read statuses
statuses.updateUpdate statuses
statuses.deleteDelete statuses
sources.createCreate contact sources
sources.readList / read sources
sources.updateUpdate sources
sources.deleteDelete sources
groups.createCreate groups
groups.readList / read groups
groups.updateUpdate groups
groups.deleteDelete groups
templates.readList / read WhatsApp templates
templatebots.read / templatebots.deleteRead / delete template-bot definitions
messagebots.create / messagebots.read / messagebots.deleteManage message-bot definitions
messages.sendSend text, template, media messages; validate phone numbers; check message status
Because every token holds every ability, there is no “missing ability” scenario in normal use. The 403 Token does not have the required ability error only fires if abilities are removed via direct configuration on the server.

​
Rotating a token

To invalidate the current token and issue a new one:
1

Open Settings → API Management

Same page used to generate the original token.
2

Click Generate New Token

The displayed token is replaced immediately. Save the new value to your secrets manager.
3

Save

Click Save. The previous token stops working as soon as the change is persisted.
Rotation is a hard cutover — there is no grace period. Update every integration with the new token at the same time you save, or your integrations will start receiving 401 Invalid API token.

​
Revoking access

To stop all API access without issuing a new token, flip the Enable API Access toggle off in Settings → API Management and save. Every subsequent request returns: 
{
  "status": "error",
  "message": "API access is disabled"
}
Toggle the switch back on later to re-enable the existing token.

​
Rate limits

Default: 60 requests per minute per token (configurable per workspace). When the limit is exceeded, the API responds with 429 Too Many Requests and a retry_after field (in seconds). See Rate Limits for the full details and headers.

​
Errors

​
Missing token

HTTP 401: 
{
  "status": "error",
  "message": "API token is required"
}

​
Invalid token

HTTP 401: 
{
  "status": "error",
  "message": "Invalid API token"
}

​
API disabled

HTTP 403: 
{
  "status": "error",
  "message": "API access is disabled"
}

​
Missing ability

HTTP 403 (rare — only when an ability has been removed server-side): 
{
  "status": "error",
  "message": "Token does not have the required ability: contacts.create"
}

​
Security checklist

Store the token in a secrets manager — never commit it to source control.
Rotate the token on a regular cadence or whenever a team member with access leaves.
Disable API access entirely if you suspect leakage, then rotate.
Always use HTTPS — the token travels in the Authorization header on every request.