Authentication

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

Open API Management

In your dashboard, go to Settings → API Management.

Enable API access

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

Copy the token

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

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):

Ability	Grants
`contacts.create`	Create contacts
`contacts.read`	List / read contacts
`contacts.update`	Update contacts
`contacts.delete`	Delete contacts
`statuses.create`	Create contact statuses
`statuses.read`	List / read statuses
`statuses.update`	Update statuses
`statuses.delete`	Delete statuses
`sources.create`	Create contact sources
`sources.read`	List / read sources
`sources.update`	Update sources
`sources.delete`	Delete sources
`groups.create`	Create groups
`groups.read`	List / read groups
`groups.update`	Update groups
`groups.delete`	Delete groups
`templates.read`	List / read WhatsApp templates
`templatebots.read` / `templatebots.delete`	Read / delete template-bot definitions
`messagebots.create` / `messagebots.read` / `messagebots.delete`	Manage message-bot definitions
`messages.send`	Send 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:

Open Settings → API Management

Same page used to generate the original token.

Click Generate New Token

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

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.

Introduction

API Reference

Webhooks

Data Types

Authentication

Token format

Generating a token

Using a token

Abilities

Rotating a token

Revoking access

Rate limits

Errors

Missing token

Invalid token

API disabled

Missing ability

Security checklist

​Token format

​Generating a token

​Using a token

​Abilities

​Rotating a token

​Revoking access

​Rate limits

​Errors

​Missing token

​Invalid token

​API disabled

​Missing ability

​Security checklist

Token format

Generating a token

Using a token

Abilities

Rotating a token

Revoking access

Rate limits

Errors

Missing token

Invalid token

API disabled

Missing ability

Security checklist