API Tokens

How personal API tokens are issued, checked and retired.

Personal API tokens authenticate requests to /api/v1. Each token belongs to exactly one workspace and acts on behalf of the member who created it.

Lifecycle

1. Creation

• Only members whose role includes Manage API tokens can create tokens (owners, admins, members — not viewers).
• Every requested ability must be permitted by the creator's current role.
• An optional expiry must be in the future.
• Pingi generates pingi_ + 40 random characters. The response shows this once. Pingi stores only:
  • a SHA-256 hash of the token (used for lookup),
  • the last four characters (so you can recognise it in lists),
  • name, abilities, expiry, creator and workspace.
• The creation is written to the audit log — without the token.

2. Use

Send Authorization: Bearer pingi_…. On every request Pingi:

1. hashes the presented value and looks it up;
2. rejects it unless it is unrevoked, unexpired, and its creator is still a member of the token's workspace;
3. scopes the whole request to that one workspace — records of other workspaces resolve as not found;
4. requires the endpoint's ability on the token and the matching permission in the creator's current role;
5. applies the workspace plan's per-token rate limit;
6. records last-used time and IP (at most once a minute).

Changing the creator's role never widens a token: promotion adds no abilities the token lacks, and demotion immediately removes the power of abilities the new role no longer allows.

3. End of life

A token stops working the moment any of these happens:

Where tokens never appear

• Database: hashes only.
• Application logs, the audit log and API responses (including the token-introspection endpoint): never the raw token.
• Request inspection (Telescope): the Authorization header and one-time secrets in responses are masked in every environment.