Authentication

Use the public authentication routes to start a client session. All request bodies are JSON.

Log in

POST /apis/v1/auth/login

{
  "user": {
    "username": "person@example.com",
    "password": "your-password"
  }
}

A successful response returns access_token, refresh_token, token_type (Bearer), expires_in, and requires_2fa. Send the access token in the Authorization header for protected routes.

If requires_2fa is true, complete the account’s TOTP step before treating the client as fully authenticated. See the product 2FA guide for the user flow.

Refresh a session

POST /apis/v1/auth/refresh

Provide refresh_token either at the top level or under user.refresh_token. Ration rotates the refresh token and returns a new bearer access token. An invalid or expired refresh token returns 401 with invalid_refresh_token.

Sign out

POST /apis/v1/auth/logout or DELETE /apis/v1/auth/logout

This is a protected route. Send the bearer token. An optional user.username identifies the account; otherwise the authenticated user is used.

Password recovery

Operation	Route	Request
Start recovery	POST /apis/v1/auth/reset-password	{"user":{"login":"person@example.com"}} (email or username may also be used)
Finish recovery	POST /apis/v1/auth/update-password	email, temp_user_key, and password

Recovery initiation is rate limited. The completion route validates the temporary reset key and returns 401 when it is invalid, expired, or associated with a different email.

Two-factor management

These routes are protected and operate on the authenticated user:

Method	Route	Purpose
POST	/auth/initiate-2fa	Start TOTP setup.
POST	/auth/enable-2fa	Enable the newly configured factor.
POST	/auth/verify-2fa	Verify a TOTP code.
POST	/auth/disable-2fa	Disable TOTP after the required verification.

Never log or persist a TOTP setup secret, QR payload, token, access token, or refresh token.

For profile settings, signatures, application-specific passwords, and the detailed TOTP contract, see the Settings API.