/api/v1. All responses use the standard envelope format: { "success": true, "data": … } or { "success": false, "error": { "code": "…", "message": "…" } }.
Auth /api/v1/auth
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /register | None | Register a new user. Returns 201, no tokens — user must verify email before logging in. |
| POST | /login | None | Login with email and password. Returns access + refresh tokens. |
| POST | /refresh | None | Exchange a valid refresh token for a new token pair. Old token is revoked. |
| POST | /logout | Bearer | Revoke the current refresh token. |
| GET | /verify-email | None | Verify email address with ?token= query param. Returns token pair on success. |
| POST | /resend-verification | None | Resend verification email. Always returns 200 — no email enumeration. |
| POST | /forgot-password | None | Request a password reset email. Always returns 200 — no email enumeration. |
| POST | /reset-password | None | Reset password with token from email. Revokes all existing refresh tokens. |
| POST | /change-password | Bearer | Change password with current password confirmation. Revokes all refresh tokens. |
| POST | /magic-link/request | None | Request a magic link login email. Always returns 200. |
| GET | /magic-link/verify | None | Verify magic link with ?token= query param. Returns token pair. |
| GET | /me | Bearer | Return the current user’s profile and active tenant context. |
| GET | /google | None | Initiate Google OAuth flow. Redirects to Google. |
| GET | /google/callback | None | Google OAuth callback. Redirects to frontend with tokens. |
| GET | /github | None | Initiate GitHub OAuth flow. Redirects to GitHub. |
| GET | /github/callback | None | GitHub OAuth callback. Redirects to frontend with tokens. |
Tenants /api/v1/tenants
| Method | Path | Auth | Permission | Description |
|---|---|---|---|---|
| POST | / | Bearer | None | Create a new tenant (workspace). |
| GET | /mine | Bearer | None | List all tenants the current user belongs to. |
| POST | /switch | Bearer | None | Switch active tenant. Returns a new token pair with the new tenant context. |
| GET | /current | Bearer | tenant.settings.read | Get current tenant details. |
| PATCH | /current | Bearer | tenant.settings.edit | Update tenant name or slug. |
| GET | /current/members | Bearer | tenant.members.read | List all members of the current tenant with their roles. |
| POST | /current/invitations | Bearer | tenant.members.invite | Invite a user to the current tenant by email. |
| GET | /current/invitations | Bearer | tenant.members.read | List pending and recently expired invitations. |
| DELETE | /current/invitations/{id} | Bearer | tenant.members.invite | Cancel a pending invitation. |
| POST | /invitations/accept | Bearer or None | None | Accept an invitation token. Returns token pair or REGISTRATION_REQUIRED. |
| DELETE | /current/members/{userId} | Bearer | tenant.members.remove | Remove a member from the tenant. Cannot remove the Owner. |
| POST | /current/transfer-ownership | Bearer | tenant.ownership.transfer | Transfer the Owner role to another member. |
| GET | /current/roles | Bearer | tenant.roles.read | List all roles (built-in and custom) for the tenant. |
| POST | /current/roles | Bearer | tenant.roles.manage | Create a custom role. |
| PUT | /current/roles/{roleId} | Bearer | tenant.roles.manage | Update a custom role’s name or permissions. |
| DELETE | /current/roles/{roleId} | Bearer | tenant.roles.manage | Delete a custom role. Fails if members are assigned to it. |
| PATCH | /current/members/{userId}/role | Bearer | tenant.roles.manage | Assign a role to a member. |
Billing /api/v1/billing
| Method | Path | Auth | Permission | Description |
|---|---|---|---|---|
| GET | / | Bearer | tenant.billing.read | Get current tenant’s subscription status and plan. |
| POST | /checkout | Bearer | tenant.billing.manage | Create a Stripe Checkout session for a plan upgrade. Returns { checkoutUrl }. |
| POST | /portal | Bearer | tenant.billing.manage | Create a Stripe Customer Portal session. Returns { portalUrl }. |
Users /api/v1/users
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /profile | Bearer | Get the current user’s profile (display name, avatar, timezone). |
| PATCH | /profile | Bearer | Update display name, avatar URL, or timezone. |
| POST | /change-email | Bearer | Request an email address change. Sends verification to the new address. |
| GET | /verify-email-change | None | Complete email change with token from email. |
| DELETE | /account | Bearer | Delete the current user’s account. Requires password confirmation. |
Notifications /api/v1/notifications
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | / | Bearer | List notifications for the current user in the current tenant. Paginated. |
| GET | /unread-count | Bearer | Get the unread notification count. Redis-cached, 30-second TTL. |
| POST | /{id}/read | Bearer | Mark a single notification as read. |
| POST | /read-all | Bearer | Mark all notifications as read for the current user in the current tenant. |
Admin /api/v1/admin
All admin endpoints require is_admin = true in the JWT claims.
| Method | Path | Description |
|---|---|---|
| GET | /users | List all users. Supports search, page, pageSize query params. |
| GET | /tenants | List all tenants. Supports search, page, pageSize. |
| GET | /tenants/{tenantId} | Get tenant detail: members, subscription history, last 20 audit log entries. |
| GET | /subscriptions/overview | Aggregate subscription stats: active count, trialing, past due, estimated MRR. |
| POST | /users/{userId}/impersonate | Issue a JWT for the target user with impersonator_id claim. |
| PATCH | /tenants/{tenantId}/subscription | Manual subscription status override (local state only, does not touch Stripe). |
| DELETE | /users/{userId} | Soft-delete a user. Cancels Stripe subscription at period end. |
Webhooks
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/v1/webhooks/stripe | Stripe-Signature header | Receive and process Stripe webhook events. Returns 200 for all events, handled or not. |
Health
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /health | None | Returns {"status":"healthy"}. Used by load balancers and monitoring. |