Authentication

Two calls turn an API key into a bearer token. challenge hands out a one-time nonce; redeem proves the caller holds the key by signing it, and answers with the token. Neither needs a token itself: both are made with the key's prefix in the X-API-Key header.

The Authentication guide walks through the handshake with a full example.

/api/auth/jwt/challenge/

Send the key's prefix in the X-API-Key header and no body. The answer is a request_id and nonce to sign, when they stop being good (expires_at), and which algorithm to sign them with.

POST

Answers 201:

{
  request_id: string,
  nonce: string,
  expires_at: string,           // ISO datetime: redeem before then
  algorithm: "hmac-sha256" | "ed25519",
  message_format: string,       // what to sign, as a reminder
  permissions_format: string,
}

/api/auth/jwt/redeem/

Send the key's prefix in X-API-Key again. challenge is the signed message, unix_ts the time it was signed at, and permissions an optional list of the permissions wanted, which must be the ones that were signed. The answer is the bearer token, its expires_at, the permissions it carries and any that were asked for and declined.

POST

Answers:

{
  token: string,                // send as "Authorization: Bearer <token>"
  expires_at: int,              // Unix seconds
  permissions: [string],        // what the token carries
  declined: [string],           // asked for, but not held by the key
}