API: auth
POST /api/v1/auth/agent-token
Section titled “POST /api/v1/auth/agent-token”Mint Agent Token
SPEC-084 §2.7 — mint (or rotate) a scoped AGENT token + its contract grants.
Superuser-only. Creates/serves a role="agent", api_scope="agent" user and
REPLACES its agent_contract_grant rows with body.grants (default-deny — a
contract not listed is inaccessible). Changing the pool/capabilities later is
a grant-row edit, no re-mint needed. publish is granted only when listed
explicitly (SPEC-084 §2.1: withhold on prod contracts by default).
POST /api/v1/auth/login
Section titled “POST /api/v1/auth/login”Login
OAuth2 password flow. username field is the user’s email.
GET /api/v1/auth/me
Section titled “GET /api/v1/auth/me”Me
POST /api/v1/auth/refresh
Section titled “POST /api/v1/auth/refresh”Refresh
Exchange a refresh token for a new access token.
POST /api/v1/auth/service-token
Section titled “POST /api/v1/auth/service-token”Mint Service Token
Mint (or rotate) a long-lived READ-ONLY access token for an external agent.
Superuser-only. The endpoint can only create/serve users with
role="agent", api_scope="read" — it is structurally unable to hand out
full-access tokens. Re-minting reactivates a previously revoked user.
DELETE /api/v1/auth/service-token/{guid}
Section titled “DELETE /api/v1/auth/service-token/{guid}”Revoke Service Token
Revoke a read-only service user: deactivate + kill all minted tokens.
Effective immediately — auth re-reads the user row on every request.
Only role="agent", api_scope="read" users are addressable here (404 otherwise),
so a typo’d guid can never lock out a human/admin account.
| Parameter | In | Required | Type |
|---|---|---|---|
guid | path | yes | integer |