A description generated from the thing it describes

Exactly what its scopes say, on the subset of operations that have been explicitly opened to token authentication. Everything else answers 401 to a token, however senior its owner is. The scope vocabulary is closed: reading channels, reading and writing messages, adding reactions, reading users, and reading and writing tasks. Asking for a scope that is not in the list is refused rather than quietly dropped.

• channels:read, messages:read, messages:write, reactions:write, users:read, tasks:read, tasks:write
• An unrecognised scope is an error, not an ignored field
• A token reaches a deliberately narrow slice of the surface; the rest answers 401
• Scopes narrow what an account can do — they never widen it

Every token has an expiry, because a policy with a “never” option is not a policy. You choose between one and 365 days, and ninety is the default. Expiry, revocation and the owner’s status are resolved together in a single query, so there is no gap between deactivating an account and its credentials going dead.

• Anyone can mint and revoke their own personal access tokens from account settings
• An administrator mints and revokes bot tokens from the console
• The value is shown once; only its hash is stored
• Deactivating the owner kills the token at the next call, without a separate revocation step

Because it is not documentation in the usual sense. The OpenAPI document is generated from the server’s own route definitions and committed to the repository, and a continuous-integration job regenerates it on every change and fails the build on any difference. A description that cannot drift is worth more than one that is merely thorough.

• Generated from the code, not maintained beside it
• A drift check in CI, so the two cannot diverge quietly
• A TypeScript client is generated from the same document
• The same document drives a generated cross-organisation probe suite that fails the build if isolation regresses