Authentication

The Aurion API uses API key authentication. Include your key in the X-API-Key header with every request.

curl -H "X-API-Key: ak_live_xxxx" \
  https://apps.aurionai.net/api/v1/tickets

API Key Scopes

Each API key is assigned one or more scopes that control which endpoints it can access.

Scope	Description	Endpoints
`tickets:read`	Read tickets and ticket history	`GET /tickets`, `GET /tickets/:id`
`tickets:write`	Create and update tickets	`POST /tickets`, `PUT /tickets/:id`
`kb:read`	Read knowledge base articles	`GET /kb/articles`, `GET /kb/articles/:id`
`kb:write`	Create and update KB articles	`POST /kb/articles`, `PUT /kb/articles/:id`
`users:read`	List and view users	`GET /users`, `GET /users/:id`
`webhooks:manage`	Manage webhook subscriptions	`POST /webhooks`, `DELETE /webhooks/:id`
`calls:read`	View call recordings and logs	`GET /calls`, `GET /calls/:id`
`usage:read`	View usage and billing data	`GET /usage`
`config:read`	Read tenant configuration	`GET /configuration/*`
`config:write`	Update tenant configuration	`PUT /configuration/*`

Scope Enforcement

Scopes are enforced using path-prefix matching. A key with tickets:read can access any GET endpoint under /api/v1/tickets/.

Write scopes grant access to POST, PUT, PATCH, and DELETE methods on the matching path prefix.

Denied Paths

The following paths are never accessible via API keys regardless of scopes:

/api/v1/super-admin/* — Platform administration
/api/configuration/api-keys — API key management (use the dashboard)
/api/sync/* — Internal sync endpoints

Error Responses

401 Unauthorized — Missing or invalid API key:

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden — Valid key but insufficient scope:

{
  "error": "forbidden",
  "message": "API key lacks required scope: tickets:write"
}

End-User Authentication

End-user endpoints (mobile app, voice widget) use JWT Bearer tokens instead of API keys:

curl -H "Authorization: Bearer eyJhbGciOi..." \
  https://apps.aurionai.net/api/v1/app/tickets

End-user tokens are issued via SSO, password login, or magic link. See the End-User API guide for full authentication details.

API Key Management

Manage API keys programmatically. These endpoints require tenant_admin or higher role.

Create API Key

curl -X POST "https://apps.aurionai.net/api/v1/api-keys" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "description": "Key for automated deployments",
    "scopes": ["tickets:read", "tickets:write"],
    "expires_in_days": 365
  }'

Response (201 Created):

{
  "id": "key_abc123",
  "name": "CI/CD Pipeline",
  "key_prefix": "ak_live_abc",
  "scopes": ["tickets:read", "tickets:write"],
  "expires_at": "2027-04-09T00:00:00Z",
  "api_key": "ak_live_xxxxxxxxxxxx"
}

The full api_key value is returned only once at creation time. Store it securely.

Rotate API Key

Generate a new key with the same scopes, revoking the old one:

curl -X POST "https://apps.aurionai.net/api/v1/api-keys/key_abc123/rotate" \
  -H "X-API-Key: ak_live_xxxx"

Response:

{
  "id": "key_def456",
  "key_prefix": "ak_live_def",
  "scopes": ["tickets:read", "tickets:write"],
  "api_key": "ak_live_yyyyyyyyyyyy"
}

Revoke API Key

Immediately deactivate a key without deleting it:

curl -X POST "https://apps.aurionai.net/api/v1/api-keys/key_abc123/revoke" \
  -H "X-API-Key: ak_live_xxxx"

Returns 204 No Content.

Delete API Key

curl -X DELETE "https://apps.aurionai.net/api/v1/api-keys/key_abc123" \
  -H "X-API-Key: ak_live_xxxx"

Returns 204 No Content.

Best Practices

Least privilege — Only grant the scopes your integration needs
Rotate regularly — Create new keys and retire old ones periodically
Never commit keys — Use environment variables, not source code
One key per integration — Makes it easy to revoke access per integration

Authentication

On this page