ShrubberyDocs
Sign in

Managing API Tokens

Overview

API Tokens are bearer credentials that let external systems authenticate against the Shrubbery API (/api/v1/inbox and /api/v1/sync). This guide covers minting, using, and revoking tokens from the /settings panel.

Actors

  • Lead — the only actor who can mint or revoke tokens. Tokens are scoped to the Lead's user_id; any API call made with a token creates or modifies rows on behalf of that Lead.
  • External System — the consumer of the token. Presents it as Authorization: Bearer <token> on every request.
  • Knight — not involved in token management.

Flow

Minting a token

  1. Lead navigates to /settings → API Tokens section.
  2. Lead clicks Generate new token.
  3. System creates a token, stores its hash in the api_tokens table, and displays the raw value once — this is the only time the full token is visible. The Lead copies it immediately.
  4. The settings panel shows only the token_prefix (the first characters of the raw value) after this point, for identification.

Using a token

  1. External System sends requests with the header: 
    Authorization: Bearer <token>
  2. verifyBearer middleware validates the hash, extracts the user_id, and enforces that the token's owner matches the assigner on any row being created or mutated.

Revoking a token

  1. Lead navigates to /settings → API Tokens, finds the token by its token_prefix, and clicks Revoke.
  2. The hash is deleted from api_tokens. All subsequent requests using that token receive 401 Unauthorized immediately.

Edge cases

  • Lost token — if the raw value is lost before being copied, there is no recovery path. Revoke the old token and mint a new one.
  • Multiple tokens — a Lead may mint one token per external system (recommended) or use a single token for all systems. Revoking one token does not affect others.
  • Token scoping — tokens are scoped to user_id only, not to specific endpoints or external systems. A token that can call /api/v1/inbox can also call /api/v1/sync.
  • Webhook retries — both the Inbox and Sync endpoints are idempotent on (external_system, external_id, assigner). Webhook delivery retries with the same payload are safe.

Last updated: 22 June 2026