---
title: "Auth & Onboarding"
description: "Register, log in with or without two-factor, manage sessions, and create your first organization — the calls every integration starts with."
url: "https://bareledger.app/guides/api-auth"
category: "Developers & API"
updated: "2026-10-04"
publisher: "BareLedger (Syneria Technologies OPC)"
---

# Auth & Onboarding

> Register, log in with or without two-factor, manage sessions, and create your first organization — the calls every integration starts with.

All paths relative to `/api/v1/`. See [API Authentication](https://bareledger.app/guides/api-authentication) for the full flow and [API Error Reference](https://bareledger.app/guides/api-errors) 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 | — |