Authentication and tokens

This article and the rest of the API documentation in this section are written for a technical audience — integrators and developers connecting external systems to Tickiti. Familiarity with HTTP, REST, JSON and bearer-token authentication is assumed.

The Tickiti API authenticates with bearer tokens. Each token has a description (so you can tell them apart) and a set of abilities that gate which endpoints it can call. Tokens are managed at Administration → API keys in the admin user-menu dropdown. The page is admin-only and additionally requires the can_manage_api_keys plan capability.

Abilities

1. tickets:read — read-only access to the ticket list via POST /api/v1/tickets/query.
2. tickets:write — create tickets via POST /api/v1/tickets and post responses via POST /api/v1/tickets/respond.
3. Write implies read — a tickets:write token can also call the query endpoint, so you rarely need to grant both.
4. Abilities follow a <family>:<access> convention, where the family mirrors a section of the Tickiti menu and access is read or write. The families are tickets, settings, mail, templates, workflow, reports, supervisor and administration; each requires the matching role (staff, admin or superuser) and the API keys screen only offers the abilities your own role can grant. Each family’s reference page lists its endpoints.

Pick the minimum set the integration actually needs. A CRM that only files and updates tickets needs tickets:write; a dashboard that only reads the ticket list needs tickets:read.

Creating a token

1. Open Administration → API keys.
2. Click Add key.
3. Choose who the key acts as — a staff user, or System (the default). API calls run with that user’s own permissions.
4. Enter the source system name (e.g. Sales Portal) — the external system that will call the API.
5. Choose the access each family needs — for Tickets, pick Read or Read & write.
6. Review the description; it is built automatically from the fields above and can be edited freely.
7. Click Add key. Tickiti shows the bearer token once; copy it into your integration’s secret store immediately.

Using a token

Send the token in the Authorization header on every request:

Authorization: Bearer 14|wfNxV4zX8PqR9K2j7L6M5N0BeQa3D1cGtY

Tokens are bound to a built-in system user, not to a specific staff account. They survive staff coming and going from your team. Anything an integration does via the API attributes to the system user on the staff side of the conversation.

Rotating and revoking

1. To rotate: create a new token with the same abilities, switch the integration over, then delete the old one.
2. To revoke: click the trash icon on the row in API keys. The token stops working immediately on the next request.
3. To audit: each row shows a Last used timestamp. Tokens with no recent use are candidates for cleanup.

If a token leaks

Delete the token immediately. Anything an attacker did with it before deletion is in the audit trail (sent emails appear in Mail → Sent mail, created tickets appear with the system user as the staff side). Replace it with a fresh one and update the integration.

Token storage on your side

1. Store tokens in your platform’s secret manager (Vault, AWS Secrets Manager, Azure Key Vault, Doppler, etc.) — never check them into git.
2. Inject them via environment variables, not config files committed to the repo.
3. If you must put a token in a CI pipeline, use the CI provider’s secret feature, not plain text.

Where to go next

1. API overview — the API surface and which abilities gate which endpoints.
2. Idempotency — the Idempotency-Key header required on write endpoints.
3. Create ticket API, Reply to ticket API and List tickets API — full request/response references for each endpoint.