Auth API
Manage end-user authentication within your tenant. All auth endpoints require a tenant API key (X-API-Key).
POST
/api/v1/auth/registerRegister User
Register a new end-user within your tenant. Returns a user object and JWT tokens.
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | User email address |
password | string | No | Password (omit for passwordless/magic-link flow) |
username | string | No | Display username |
externalUserId | string | No | Your system's user ID for linking |
displayName | string | No | Display name |
metadata | object | No | Custom metadata (key-value pairs) |
Example
bash
curl -X POST "https://api.puzzlesection.app/api/v1/auth/register" \ -H "X-API-Key: ps_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "username": "puzzlefan42", "externalUserId": "your-user-id-123" }'Response 201
JSON
1{2 "user": {3 "id": "550e8400-e29b-41d4-a716-446655440000",4 "email": "user@example.com",5 "username": "puzzlefan42",6 "tenantId": "tenant-uuid"7 },8 "userToken": "eyJhbGciOiJIUzI1NiIs...",9 "refreshToken": "eyJhbGciOiJIUzI1NiIs...",10 "isNewUser": true11}POST
/api/v1/auth/loginLogin
Authenticate an existing user with email and password.
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | User email |
password | string | Yes | User password |
Response 200
JSON
{ "user": { "id": "...", "email": "...", "username": "..." }, "userToken": "eyJ...", "refreshToken": "eyJ..."}POST
/api/v1/auth/refreshRefresh Token
Exchange a refresh token for a new token pair.
| Parameter | Type | Required | Description |
|---|---|---|---|
refreshToken | string | Yes | Current refresh token |
Response 200
JSON
{ "userToken": "eyJ...", "refreshToken": "eyJ..."}POST
/api/v1/auth/magic-linkRequest Magic Link
Send a passwordless login link to the user's email.
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | User email |
redirectUrl | string | No | URL to redirect after verification |
Response 200
JSON
{ "message": "Magic link sent", "sent": true }POST
/api/v1/auth/magic-link/verifyVerify Magic Link
Verify the token from a magic link email. Returns user and JWT tokens.
| Parameter | Type | Required | Description |
|---|---|---|---|
token | string | Yes | Magic link token from email |
Response 200
JSON
{ "user": { "id": "...", "email": "...", "username": "..." }, "userToken": "eyJ...", "refreshToken": "eyJ...", "isNewUser": false}GET
/api/v1/auth/meGet Current User
Returns the authenticated user's profile. Requires both X-API-Key and X-User-Token.
Response 200
JSON
{ "user": { "id": "550e8400-...", "email": "user@example.com", "username": "puzzlefan42", "tenantId": "tenant-uuid" }, "tokenBalance": 50}POST
/api/v1/auth/logoutLogout
Invalidate the current user session. Requires both API key and user token.
Response 200
JSON
{ "message": "Logged out successfully" }Auth Error Codes
| Code | Description |
|---|---|
USER_EXISTS | Email already registered in this tenant |
USERNAME_EXISTS | Username already taken |
INVALID_CREDENTIALS | Wrong email or password |
USER_DEACTIVATED | Account has been deactivated |
NO_PASSWORD | User registered without password (use magic link) |
MAGIC_LINK_EXPIRED | Magic link token has expired |
MAGIC_LINK_USED | Magic link has already been used |
TENANT_MISMATCH | User belongs to a different tenant |