ShrubberyDocs
Sign in

API Token

Definition

A bearer credential minted by the Lead in /settings that authenticates external systems against the Shrubbery API (/api/v1/inbox and /api/v1/sync).

Avoid: API key, webhook secret, access token (reserved for OAuth contexts).

Role

API Tokens enable the Shrubbery Inbox and Sync webhook endpoints for programmatic use. An external system (Jira, Linear, GitHub, a custom script) presents the token as a Bearer header; verifyBearer middleware validates the hash and enforces that the token is scoped to the token.user_id that minted it — a token from one Lead cannot write rows for another.

Each token is stored hashed in the api_tokens table. The raw value is shown exactly once at mint time (copy-once display); after that, only the token_prefix (the first characters) is visible in the UI for identification. Lost tokens must be revoked and re-minted.

A Lead can mint multiple tokens (e.g. one per external system) and revoke individual tokens from /settings without affecting others.

Lifecycle

  • Mint — Lead generates a token in /settings; raw value shown once, hash stored.
  • Authenticate — external system sends Authorization: Bearer <token> on each request; verifyBearer validates.
  • Revoke — Lead removes a token from /settings; hash deleted; all future requests with that token return 401.

Last updated: 22 June 2026