Authentication & Sessions
Tag: Auth · Version: v1 · Stability: 🟢 Stable (OAuth: 🟡 Beta)
Human authentication for the Paperwright platform. These endpoints issue and
manage the JWT used as Authorization: Bearer <token> on every management
call. (Machine rendering uses an API key instead.)
:::info Versioning All endpoints on this page are v1 / 🟢 Stable except the two OAuth endpoints, which are 🟡 Beta. Within v1, changes are additive only — see the versioning policy. :::
Sign up
POST /api/auth/signup · Public
{ "email": "you@example.com", "password": "••••••••" }
Both fields are required. Creates the user and their first workspace, and sends a verification email.
Log in
POST /api/auth/login · Public
{ "email": "you@example.com", "password": "••••••••" }
Returns a session JWT (carrying the user's active workspace and role claim).
Email verification
| Endpoint | Body | Notes |
|---|---|---|
POST /api/auth/verify-email | VerifyEmailBody { token } | Confirms an address from the emailed token. |
POST /api/auth/resend-verification | EmailBody { email } | Re-sends the verification email. |
Password reset
| Endpoint | Body | Notes |
|---|---|---|
POST /api/auth/forgot-password | EmailBody { email } | Sends a reset link. |
POST /api/auth/reset-password | ResetPasswordBody { token, newPassword } | Sets a new password from the emailed token. |
POST /api/auth/change-password | ChangePasswordBody { currentPassword, newPassword } | JWT — change while logged in. |
Session lifecycle
| Endpoint | Auth | Notes |
|---|---|---|
POST /api/auth/refresh | Cookie/JWT | Exchanges a refresh token for a fresh session JWT. |
POST /api/auth/logout | JWT | Ends the current session. |
POST /api/auth/logout-all | JWT | Revokes every session for the user. |
GET /api/auth/me | JWT | Returns the current user, active workspace, and role. |
Switch workspace
POST /api/auth/switch-workspace/{workspaceId} · JWT
{workspaceId} is a UUID. Returns a new JWT scoped to that workspace (with
the matching role). Replace the stored token and refetch workspace-scoped data
after switching.
OAuth (social login) — 🟡 Beta
| Endpoint | Query | Notes |
|---|---|---|
GET /api/auth/oauth/{provider}/start | redirect? | Begins the OAuth flow; redirects to the provider. |
GET /api/auth/oauth/{provider}/callback | code?, state? | Provider redirect target; completes the flow and issues a session. |
{provider} is a string (e.g. google). Marked Beta — the provider set and
redirect handling may still change within v1.
Related
- API Keys — machine auth for rendering.
- Workspaces & Invites — roles and membership.