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 — the ticket read endpoints: the ticket list (POST /api/v1/tickets/query), single tickets, responses, attachments, links and the lookups.
2. tickets:write — everything that changes a ticket: create tickets via POST /api/v1/tickets, post responses via POST /api/v1/tickets/respond, close, change participants, correct responses, and the ticket operations.
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.

A token can only grant abilities it holds itself. Keys created or changed through the API (see Managing keys through the API below) are therefore limited to the calling token’s own abilities: the API narrows and rotates keys, and a key with wider access is created in Administration → API keys.

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

A token acts as the user chosen when it was created. Tokens owned by the built-in System user (the default) are not tied to a specific staff account, so they survive staff coming and going from your team, and anything an integration does with them attributes to the system user on the staff side of the conversation.

Checking what a token can do

Any token can ask what it is allowed to do — no ability is needed:

curl -X POST https://support.sole-provider.example/api/v1/token \
  -H "Authorization: Bearer $TOKEN"

The response describes the token (name, abilities, expires_at, last_used_at, allowed_ip), its owner (email, name and role flags), each ability family (whether the token holds read and write, the role the family needs, and whether the owner has it), and the plan’s features. When a call is refused with 403, this tells you whether the token lacks the ability, its owner lacks the role, or the plan lacks the feature. See Ticket operations API for the full field list.

Managing keys through the API

API keys can be listed, created, changed and revoked through the Administration API. These endpoints need the administration ability and a token whose owner is an admin, and they manage the same keys the API keys screen shows:

1. POST /api/v1/administration/api-tokens (administration:read) — every key with its owner, abilities, IP allow-list and timestamps, plus grantable: the abilities the calling token may hand out.
2. POST /api/v1/administration/api-tokens/create (administration:write) — name, owner (system or a staff user id), abilities and an optional allowed_ip. Returns the bearer token once, in plain_text_token.
3. POST /api/v1/administration/api-tokens/update (administration:write) — id, plus any of abilities, allowed_ip (null clears it) and name.
4. POST /api/v1/administration/api-tokens/revoke (administration:write) — id. The key stops working at once.

A create or ability change may only grant abilities the calling token holds itself (holding write covers read), and the key’s owner must hold the role each ability needs. Anything beyond the calling token is refused with 403, naming the missing abilities; grant those in Administration → API keys.

Rotating and revoking

1. To rotate: create a new token with the same abilities, switch the integration over, then delete the old one. Through the API, a token holding administration:write and the key’s abilities can do the same with api-tokens/create and api-tokens/revoke.
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. Administration API — the API-key endpoints alongside the rest of the Administration screens.
4. Create ticket API, Reply to ticket API and List tickets API — full request/response references for each endpoint.