Authentication

The Tickr public API uses API keys (bearer tokens). Every request must carry the key in the Authorization header:

Authorization: Bearer tkr_live_<random>

Creating an API key

Every active member of a workspace — Owner, Admin, Project Lead, Analyst or Workspace User — can create API keys for that workspace. Keys are created from the web app (a signed-in session is required: an API key can never create, list or revoke keys).

1. Sign in to Tickr and open Integrations (/integrations).
2. In the API keys card, click Create key.
3. Pick the workspace, the role the key should carry, an expiry and a name, then copy the value shown once. We store only a hash; nobody can display the key again.

A step-by-step user guide with screenshots is available in the user guide.

Key role

The role is chosen at creation time and can be at most your own role in that workspace. Allowed values: admin, project_lead, analyst, workspace_user. The owner role is not permitted for API keys (defence in depth — a leaked key must never be able to transfer ownership or delete the workspace).

Creator’s role	Roles the key may carry
owner, admin	admin, project_lead, analyst, workspace_user
project_lead	project_lead, analyst, workspace_user
analyst	analyst
workspace_user	workspace_user

The web app only offers the allowed roles. If a role above yours reaches the server anyway (e.g. your role changed meanwhile), it is silently lowered to your role. The analyst / workspace_user pair cannot be ordered (read-everything-write-nothing vs. write-your-own-entries), so asking for one while holding the other is rejected with 422 validation and errors[].code = api_key_role_incompatible.

For the MCP connector, workspace_user is the recommended role.

Expiry

The creation accepts an optional expiresInDays: 30, 90 (the UI default) or 365. Omit it for a key that never expires. Any other value is rejected with 422 validation (errors[].code = api_key_expiry_invalid). Expired keys are never re-enabled.

Limits

• At most 10 active keys per user per workspace (revoked and expired keys don’t count). Creating an 11th returns 409 conflict with detail api_key_limit_reached — revoke one first.
• At most 10 key-creation attempts per hour per user, across all workspaces; rejected attempts count too. Beyond that the server returns 429 rate_limited with the Retry-After and X-RateLimit-* headers described in Rate limits. Listing and revoking keys are not limited.
• The name is required, at most 200 characters, and must not contain control characters (line breaks, tabs…): 422 validation with errors[].code = api_key_name_invalid otherwise.

Creation email

The key’s owner receives an email each time a key is created on their account, when email is configured on the instance. It lists the key’s name, workspace, role, creation date and expiry — never the key. Delivery is best-effort: a mail failure never blocks the creation.

Who sees which keys

Owners and Admins can see and revoke every key of their workspace (each row names the key’s owner). Other members only see and revoke their own; for them another member’s key does not exist (404 not_found, same as an unknown id).

Recognizing a key in the list

Key lists never return the key itself, only its first characters (keyPrefix): tkr_live_ followed by the key’s first 6 random characters, e.g. tkr_live_ab12cd. Compare it with the start of the key your integration uses to find which row it is. Older keys, created before this format was introduced, show only tkr_live — tell them apart by their name.

Scope

• A key is scoped to one workspace — the workspace chosen when the key was created.
• The key’s role is fixed for its lifetime. To change it, revoke the key and create a new one.
• On every call, the key acts with the lower of its own role and its owner’s current role in the workspace: if the owner is demoted, the key is demoted with them immediately.
• A key only works on endpoints under /api/v1/....

Checking a key

GET /api/v1/me describes the key you are calling with: the owner (user), the workspace, the key’s frozen role (keyRole), the role it actually acts with on this request (role) and the server time (serverTime). Use it to validate a key at start-up.

Rotation

There is no in-place rotation. Create a new key, switch your integration to it, then revoke the old key. Revocation is immediate and irreversible.

Revocation and expiry

A key stops working — every call returns 401 unauthorized — when:

Event	Scope	detail of the 401
Revoked from Integrations → API keys (by its owner, or by an Owner/Admin of the workspace)	that key	Invalid or revoked API key
Its expiry date has passed	that key	API key expired
Its owner leaves the workspace or is removed from it	the owner’s keys for that workspace	Invalid or revoked API key
The workspace is deleted	every key of that workspace	Invalid or revoked API key
Its owner completes a password reset through the e-mail link (self-service or sent by an admin)	all the owner’s keys, in every workspace	Invalid or revoked API key
The owner’s current role and the key’s role become the analyst / workspace_user pair	that key	API key scope is incompatible with the owner's current role; create a new key

The password-reset row also covers keys that were being created while the reset was happening, together with every access and refresh token issued before it: sign in again with the new password and create new keys. The confirmation e-mail sent after the reset tells the user how many keys were revoked. Changing your password voluntarily from your profile revokes nothing.

Other 401 details on /api/v1: Missing or malformed Authorization header, Authorization header is not an API key (the bearer value must start with tkr_) and API key owner is no longer an active member of the workspace. Match on the status code, not on these human-readable details.

Session refresh tokens

This does not concern API keys. If you script against the session endpoints instead (POST /api/auth/refresh, cookie tickr_refresh), note that the refresh token rotates on every use: each call returns a new cookie and consumes the one you sent. Always send the latest cookie, and never refresh twice in parallel with the same one (serialize refreshes across your threads or processes). Presenting a token that was already revoked — rotated by an earlier refresh, logged out, or ended with 403 no_active_workspace — is treated as theft: the call gets 401 and every session of the user is revoked. There is no grace period: a second refresh that arrives after the first one rotated the cookie triggers it too. A token that has expired, or that was issued before a password reset, is just refused with 401 (nothing else is revoked).

Logging out (POST /api/auth/logout) revokes the cookie you send; with a cookie that is already revoked it does nothing.

A refresh refused with 403 no_active_workspace (you no longer belong to any workspace and have no pending invitation) ends the session: the presented token is revoked and the response deletes the cookie.

Last-used timestamp

We record when each key was last used, at most once every 5 minutes per key (the stored value can lag the real last call by up to 5 minutes). It is visible on the Integrations page and helps you spot dormant keys.

Example

curl -sS https://tickr.coderise.cloud/api/v1/projects \
  -H "Authorization: Bearer tkr_live_<random>" \
  -H "Accept: application/json"