[Feature]: personal API tokens

[tbcsec]

Before you start

• I searched existing issues and this isn't already requested.

What problem does this solve?

Currently authorization is handled via JWT, in and outside of the browser. Efficient for browser-based communications, but lacklustre for programmatic access to the underlying API and restricts future expansion of the API.

Proposed solution

Implement the ability to generate API tokens (individually scoped per user) for administrators of the site. Allowing programmatic access over the API without relying on capturing a JWT and submitting that as authorization.

Alternatives considered

No response

Rough size

Medium (a new screen / endpoint)

Contribution

• I'd be willing to help implement this.

[tbcsec]

Triage

What's being asked

Add user-generated personal API tokens as a first-class authentication mechanism alongside the browser JWT flow, so scripts and integrations can call the REST API without capturing and replaying an access token. Tokens are minted and revoked from an in-app screen, are scoped to the user they belong to, and authenticate requests with that user's identity and permissions.

Module(s) affected

The auth core (required-core, not a toggleable module):

• backend/auth/security.py — token creation/verification lives here; a new long-lived token type would sit beside the JWT helpers.
• backend/auth/deps.py — get_current_user would need to accept Authorization: Bearer <api-token> in addition to access JWTs (or a distinct header/prefix, e.g. flp_…, to keep the two paths unambiguous).
• backend/routers/auth.py (or a new routers/api_tokens.py mounted by the auth/users plugin) — CRUD: list / create (show plaintext once) / revoke.
• New model + migration following the existing hashed-secret pattern — store only a SHA-256 of the token, exactly like backend/models/password_reset.py (PasswordResetToken) and the ADR-0008 refresh sessions.
• Frontend: a "API tokens" section on /profile (or Admin → Users if admin-only), new hook module under frontend/src/lib/hooks/.
• Relevant ADRs: 0003 (JWT access/refresh), 0008 (stateful refresh sessions — the revocation pattern to mirror). New <entity>.<verb> events needed (e.g. user.token_created / user.token_revoked) per the §3.2 rule that every mutation emits.

Missing information

• Who can mint tokens? The problem statement says per-user, but the proposal says "for administrators of the site" — is this admin-only, gated by a new permission, or open to any account?
• Scoping model: does a token carry the holder's full permission set, or do you want restricted scopes (read-only, per-competition) in v1? Full-permission is much smaller.
• Lifetime: fixed expiry, configurable expiry, or non-expiring until revoked?
• Should token-authenticated requests be exempt from, or subject to, the same rate limits as browser sessions?

Duplicates

None open. #58 (additional authentication providers) is adjacent but distinct — that's inbound identity (SSO/LDAP), this is outbound programmatic access.

---

Generated by Claude Code