Roles and permissions

Authorisation here has two axes, checked separately, and a request has to clear both:

1. The workspace role of the person the call acts as — viewer, editor, admin or owner. Every guarded operation declares a floor.
2. The scopes on the credential, if it is an API key. Scopes decide which operations a key may reach; they never grant authority.

A key that holds * but belongs to a viewer still cannot create a ticket. A person who is an owner still cannot use a key scoped only to tickets:read to read customers. Neither axis substitutes for the other.

The four roles

They are a strict ladder. Each role can do everything the one below it can.

A floor means "this role or higher". The role is re-read from the membership record on every request — there is no cached role and no token claim to trust.

What an owner can do that an admin cannot

Exactly one rule, and it is worth knowing because it is not a list of routes:

Nobody may grant a role above their own.

An admin cannot make someone an owner, and cannot invite someone as an owner. Both attempts are refused identically:

{
  "role": "admin",
  "required_role": "owner",
  "error": "insufficient_role",
  "message": "role 'admin' cannot grant role 'owner'"
}

There is no owner-only route. No billing gate, no workspace-delete operation — an admin reaches everything an owner reaches. The difference is only in what role they may confer.

Two related protections, both 409:

• The last owner cannot be demoted — cannot demote the last owner.
• The last owner cannot be removed — cannot remove the last owner.

The three refusals, and how to tell them apart

The floors, by group

Every published operation and the floor it sits at.

Tickets and the ticket rail

Customers

Helpdesk operations — teams, macros, SLA, saved views, squads

The pattern is consistent: read at viewer, write at editor, delete at admin.

Channels

Workspace administration

Invitations

Everything else

Scopes

Scopes apply only to API keys. A session token has no scopes; it is bounded by role alone.

The grammar

A scope is derived from the operation's tag and an action:

<tag>:read      <tag>:write      <tag>:*      *

There is no fixed list of scope strings in the product — the set is derived from the live route table, so it is <tag>:read, <tag>:write or <tag>:* for any of the runtime's 67 tags, plus * for everything. That is a little over two hundred valid strings.

The 17 tags in this reference are a subset. A key can be scoped to tags this reference does not document.

Which scope an operation needs

The action follows the role floor, not the HTTP method:

• Floor is viewer → the operation needs <tag>:read.
• Floor is anything higher → the operation needs <tag>:write.

How grants match

• * grants everything.
• <tag>:* grants both actions on that tag.
• <tag>:write implies <tag>:read — on the same tag only.
• Nothing implies anything across tags.

# A key scoped ["tickets:write"] only:
GET  /v1/tickets    # 200 — write implies read
POST /v1/tickets    # 200 — direct match
GET  /v1/customers  # 403 api_key_out_of_scope: needs 'customers:read'

Scopes are case-sensitive, and a key may carry at most 64 of them.

A key with no scopes reaches nothing

Minting a key without a scopes array gives it [], and [] is refused at every operation before routing even happens:

{
  "error": "api_key_unscoped",
  "message": "this api key carries no scopes and can reach no operation"
}

That is fail-closed by design. It is not a misconfiguration you will discover slowly.

A key never outranks its owner

This is the most important property of the key model, and it is worth stating without hedging because it has been verified end to end:

A key borrows its owner's live workspace role. It holds no authority of its own.

Concretely, with one unchanged key holding *, as its owner's membership was moved underneath it:

There is no cache, no grace period, and nothing to revoke separately. Demoting a person demotes their keys on the very next request.

The honest limits of an API key

Four things a key can never do, no matter how it is scoped.

{
  "error": "api_key_identity_only",
  "message": "this operation answers for a user, and an api key acts in one workspace"
}

Revoke against delete

Both stop the key immediately and neither is reversible. They differ in what they leave behind:

Revoke when you want the audit trail — it keeps the record that the key existed and was deliberately killed. Delete when the key was a mistake you want gone.

Refusal order

When a key is presented, checks run in this order. The first failure wins, so this tells you what a given refusal has already ruled out:

api_key_invalid          (401)  unknown prefix, wrong secret, or malformed
api_key_revoked          (401)
api_key_expired          (401)
user_inactive            (403)  the owner's account is switched off
api_key_unscoped         (403)  no scopes at all
api_key_workspace_mismatch (403)
api_key_owner_not_member (403)
--- routing happens here ---
api_key_identity_only    (403)
api_key_out_of_scope     (403)
insufficient_role        (403)  the owner's role is below the floor

api_key_invalid deliberately covers three different failures, so a caller holding no valid key learns nothing from it. Everything below it is only reachable after the secret has matched, so each of those refusals tells its legitimate holder something they are entitled to know.