Authentication and scopes

How keys and scopes work, and what to do when a key stops working.

The key goes in the header

Every request carries the key in the standard header:

Authorization: Bearer tgdesk_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcd

Keys of Russian projects start with tygy_, international ones with tgdesk_. The prefix exists so a leaked key is recognisable at a glance and greppable in logs.

An app session and an API key are different things. A key does not work on internal routes, and a session does not work on /v1/. That is deliberate.

Scopes

A key carries a list of rights shaped resource:verb. Every method in the reference names the scope it needs.

Three rules you can rely on:

1. Read never grants write. conversations:read will not close a conversation.
2. Write never grants sending. conversations:write changes statuses and tags; sending a message needs messages:send on its own.
3. A key cannot exceed its creator. An admin without permission to reply to customers cannot mint a key with messages:send.

When a scope is missing

A 403 names the missing scope — no guessing:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the \"messages:send\" scope",
    "details": { "required_scope": "messages:send" },
    "request_id": "5f0f…"
  }
}

Scopes cannot be edited after a key is created. If you need a different set, create a new key and revoke the old one.

When a key does not work

A 401 means the key is dead. We deliberately do not say why — revoked, expired or never existed all look identical from outside, so probing keys tells an attacker nothing.

Check, in order:

• the key was copied whole, with no stray whitespace;
• it is not revoked in Settings → API & MCP;
• its expiry, if you set one, has not passed;
• the project is alive and the subscription is active.

Revoking

You can revoke a key at any time in the app. Revocation is immediate. A revoked key stays in the list, greyed out, so that messages it once sent keep their «API · key name» attribution in the conversation.

How actions are attributed

Everything a key does is signed with its name. A message sent through the API shows to an operator as «API · CRM sync», not as a message from a colleague. So name keys in a way people will understand: that name is what they see.