All paths relative to /api/v1/. See API Authentication for the full flow and API Error Reference for status codes.
Public
| Method & Path | Purpose | Validation | Side effects |
|---|---|---|---|
POST auth/register | Create user, send verification email | Inline | Generic response always (no enumeration oracle) |
POST auth/login | Issue bearer token or 2FA challenge | Inline | Per-email+IP rate limiting on top of route throttle |
POST auth/password/forgot | Request password reset | Inline | Generic response always |
POST auth/password/reset | Reset password via emailed token | Inline | Auto-verifies email, stamps membership accepted_at |
GET auth/email/verify/{id}/{hash} | Verify email (signed URL) | Signed-URL signature | Redirects to SPA |
POST auth/email/resend | Resend verification email | Inline | Generic response always |
GET auth/providers | Whether Google SSO is configured | — | — |
GET auth/{provider}/redirect | Redirect to Google OAuth | provider restricted to google | Mints CSRF state nonce |
GET auth/{provider}/callback | Google OAuth callback | Verifies state | Issues single-use exchange code, redirects to SPA |
POST auth/google/exchange | Trade exchange code for a bearer token | Inline | TOTP-gated if account has 2FA |
Authenticated
| Method & Path | Permission | Purpose | Side effects |
|---|---|---|---|
GET auth/me | — | Current user + memberships/roles | — |
POST auth/logout | — | Revoke current bearer token | Audit user.logout |
POST auth/2fa/enroll | — | Begin TOTP enrollment | Re-verifies password/OTP first |
POST auth/2fa/confirm | — | Confirm code, activate 2FA | Issues recovery codes, sends alert email, audit user.mfa_enrolled |
POST auth/2fa/disable | — | Disable TOTP | Sends alert email, audit user.mfa_disabled |
POST auth/2fa/recovery-codes/regenerate | — | Reissue recovery codes | Invalidates old codes, sends alert email |
Profile & Security
| Method & Path | Purpose | Side effects |
|---|---|---|
PATCH profile | Update own profile fields | Audit |
POST profile/avatar | Upload avatar | Stores file, deletes prior, audit |
POST profile/change-password | Change/first-set password | Revokes other tokens, audit |
POST profile/security-code | Email step-up code (SSO-only accounts) | Sends email |
GET profile/sessions | List active tokens | — |
DELETE profile/sessions/{tokenId} | Revoke a token | Audit |
GET profile/security-activity | Last 20 login attempts | — |
Tenant onboarding
| Method & Path | Purpose | Side effects |
|---|---|---|
GET tenants | Only the organizations the caller is registered in (own memberships) — never other tenants | — |
POST tenants | Create a new tenant/org | Provisions tenant + CoA + default roles via TenantProvisioner |
GET meta/countries | Country registry for the org-creation form | — |
GET meta/currencies | Currency registry | — |