Authentication

The Helpdesk public API authenticates requests using API keys. Each key is scoped to a specific workspace and permission level.

API key format

API keys use the prefix aclou_ followed by a random hex string:

aclou_068d7361699073144ca394135d8926f4cb1afdec

Create API keys in the Helpdesk app under Settings > API Keys.

Required headers

Every request to the public API (/api/v1/*) must include:

1. API key — via Authorization: Bearer or X-API-Key header
2. Workspace ID — via X-Workspace-Id header

curl https://app.airclou.com/helpdesk/api/v1/tickets \
  -H "Authorization: Bearer aclou_YOUR_KEY" \
  -H "X-Workspace-Id: ws_your_workspace_id"

Or using the X-API-Key header:

curl https://app.airclou.com/helpdesk/api/v1/tickets \
  -H "X-API-Key: aclou_YOUR_KEY" \
  -H "X-Workspace-Id: ws_your_workspace_id"

Permission levels

API keys are assigned one of three permission levels. Higher levels include the permissions of lower levels.

Level	Description	Example endpoints
read	Read-only access	List/retrieve tickets, fields
write	Create and update resources	Create/update/delete tickets
admin	Full access including configuration	Manage ticket fields, webhooks

Permission requirements by resource

Resource	List / Get	Create / Update / Delete
Tickets	read	write
Ticket Fields	read	admin
Ticket Field Options	read	admin
Webhooks	admin	admin

Error codes

Code	Status	Description
INVALID_API_KEY	401	API key is missing, invalid, or revoked
MISSING_WORKSPACE	400	X-Workspace-Id header is required
INSUFFICIENT_API_PERMISSION	403	API key lacks the required permission level or workspace access