Authentication

Authentication and token management

📄️Redeem a federated-login handoff code

A federated login (Google, GitHub, GitLab, Microsoft, Discord, Slack,

📄️Update the authenticated user's profile

Updates the display name and, optionally, the sign-in email.

📄️List configured auth providers

List configured auth providers

📄️Self-service account registration

Stores a pending registration and emails a confirmation link. When

📄️Confirm a pending registration with an emailed token

Confirm a pending registration with an emailed token

📄️Request a password reset email

Request a password reset email

📄️Set a new password using a reset token

Set a new password using a reset token

📄️Change (or set) the authenticated user's password

Rotates the caller's password without an emailed reset token. `currentPassword` is required when the account already has a password; for an SSO-only account (`hasPassword: false` on `/api/v1/auth/me`) it is ignored and this call sets the initial password, provided the session comes from a sign-in within the last 10 minutes (otherwise 403 `REAUTHENTICATION_REQUIRED`: sign in again first). All of the caller's *other* sessions are revoked; the calling session and any personal access tokens keep working. A confirmation email is sent. While `mustChangeEmail` is true on `/api/v1/auth/me`, the optional `email` is written in the same update as the new password (the confirmation email then goes to the new address); any other caller sending `email` gets 400.

📄️Start enabling TOTP two-factor authentication

Generates a TOTP secret for the caller (stored, not yet enabled) and returns it with a `setupToken` that `/api/v1/auth/2fa/confirm` requires. Adding a sign-in factor needs a re-authentication: `currentPassword` when the account has a password, otherwise a sign-in within the last 10 minutes. Every attempt spends the per-user change-password budget. Refused for personal access tokens and impersonation tokens.

📄️Confirm and enable TOTP two-factor authentication

Checks a code from the authenticator against the pending secret and enables two-factor authentication. Returns the recovery codes, once. `setupToken` must be the one `/api/v1/auth/2fa/setup` returned with that secret (it expires after 10 minutes). A notice email is sent to the account's address.

📄️Start registering a passkey

Returns the WebAuthn creation options and a sealed `session` to send back to `/api/v1/auth/passkeys/register/finish`. Adding a sign-in factor needs a re-authentication: `currentPassword` when the account has a password, otherwise a sign-in within the last 10 minutes.