Reference
API reference
Complete HTTP API reference for Auth Service.
API reference
Authentication for admin endpoints
All /api/admin/* routes require an active BetterAuth session cookie with the admin or superadmin role. Unauthenticated requests receive 401 AUTH_001. Authenticated requests from users without the required role receive 403 AUTH_001 (Insufficient permissions).
Health
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /health | none | Returns { "status": "ok" } |
BetterAuth (OIDC / OAuth 2.1)
All BetterAuth routes are handled at /api/auth/* by the BetterAuth request handler.
| Method | Path | Description |
|---|---|---|
POST | /api/auth/sign-up/email | Register with email + password |
POST | /api/auth/sign-in/email | Sign in with email + password |
POST | /api/auth/sign-out | Sign out (invalidate session) |
GET | /api/auth/get-session | Return the current session |
GET/POST | /api/auth/oauth2/authorize | Authorization endpoint |
POST | /api/auth/oauth2/token | Token endpoint |
GET | /api/auth/oauth2/userinfo | UserInfo endpoint |
GET | /api/auth/jwks | JSON Web Key Set |
GET | /.well-known/openid-configuration | OIDC discovery document (issuer root) |
GET | /.well-known/oauth-authorization-server | OAuth AS Metadata (RFC 8414, issuer root) |
Admin — Applications
| Method | Path | Description |
|---|---|---|
GET | /api/admin/applications | List all applications |
POST | /api/admin/applications | Create an application |
GET | /api/admin/applications/:id | Get a single application |
PATCH | /api/admin/applications/:id | Update an application |
DELETE | /api/admin/applications/:id | Delete an application |
POST | /api/admin/applications/:id/rotate-secret | Rotate client secret |
GET | /api/admin/applications/:id/users | List users with access to an application |
POST | /api/admin/applications/:id/users | Grant a user access |
PATCH | /api/admin/applications/:id/users/:userId | Update a user's access record |
DELETE | /api/admin/applications/:id/users/:userId | Revoke a user's access |
POST | /api/admin/applications/:id/users/:userId/roles/:roleId | Assign a role to a user |
DELETE | /api/admin/applications/:id/users/:userId/roles/:roleId | Unassign a role from a user |
POST | /api/admin/applications/:id/users/:userId/subscription | Assign a subscription plan |
DELETE | /api/admin/applications/:id/users/:userId/subscription | Revoke a subscription |
Admin — Roles and permissions
| Method | Path | Description |
|---|---|---|
GET | /api/admin/applications/:appId/roles | List roles (with permission IDs) |
POST | /api/admin/applications/:appId/roles | Create a role |
DELETE | /api/admin/applications/:appId/roles/:roleId | Delete a role |
GET | /api/admin/applications/:appId/permissions | List permissions |
POST | /api/admin/applications/:appId/permissions | Create a permission |
DELETE | /api/admin/applications/:appId/permissions/:permissionId | Delete a permission |
POST | /api/admin/applications/:appId/roles/:roleId/permissions/:permissionId | Assign permission to role |
DELETE | /api/admin/applications/:appId/roles/:roleId/permissions/:permissionId | Remove permission from role |
Admin — Subscription plans
| Method | Path | Description |
|---|---|---|
GET | /api/admin/applications/:appId/plans | List plans with prices and subscriber counts |
POST | /api/admin/applications/:appId/plans | Create a plan |
PATCH | /api/admin/applications/:appId/plans/:planId | Update a plan |
DELETE | /api/admin/applications/:appId/plans/:planId | Delete a plan |
POST | /api/admin/applications/:appId/plans/:planId/prices | Add a price tier |
DELETE | /api/admin/applications/:appId/plans/:planId/prices/:priceId | Remove a price tier |
Admin — Users
| Method | Path | Description |
|---|---|---|
GET | /api/admin/users | List users (paginated; ?page=1&limit=20&search=email) |
POST | /api/admin/users | Create a user manually |
GET | /api/admin/users/:id | Get a user with their application access |
PATCH | /api/admin/users/:id | Update name, global role, or isMfaRequired |
POST | /api/admin/users/:id/disable | Ban (disable) a user |
POST | /api/admin/users/:id/enable | Unban (enable) a user |
Admin — Sessions
| Method | Path | Description |
|---|---|---|
GET | /api/admin/sessions | List active sessions (paginated) |
DELETE | /api/admin/sessions/:sessionId | Revoke a session |
Admin — Services
| Method | Path | Description |
|---|---|---|
GET | /api/admin/services | Return whether optional integrations (Stripe, social providers) are configured |
Consumption
| Method | Path | Auth | Description |
|---|---|---|---|
POST | /api/consumption | Bearer token or admin session | Record a consumption entry |
GET | /api/consumption/:userId/:appId | admin session | Get aggregates for a user + app |
DELETE | /api/consumption/:userId/:appId/:key | admin session | Reset a consumption counter |
User
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /api/user/subscription | session | Return the current user's app access list with plan details |
Stripe webhooks
| Method | Path | Auth | Description |
|---|---|---|---|
POST | /api/webhooks/stripe | Stripe-Signature header | Receive Stripe subscription lifecycle events |
Auth pages
| Method | Path | Description |
|---|---|---|
GET | /login | Sign-in page (custom template or Vue SPA) |
GET | /register | Registration page (custom template or Vue SPA) |
GET | /verify-email | Email verification page (custom template or Vue SPA) |
GET | /oauth2/consent | Consent screen (Vue SPA) |