API Reference
Authentication API
Operator register, login, session, and password endpoints.
Authentication API
Operator credentials for /api/platform/*.
Source: app_docs/api.md, app_docs/guide/api.md.
Conventions
| Topic | Detail |
|---|---|
| Content type | application/json |
| Auth | Authorization: Bearer <session_token> |
| Errors | { "error": "string" } (+ optional Zod details) |
| Rate limits | Yes on auth |
| Correlation | Response x-request-id |
429: { error, code: "rate_limited" } plus Retry-After and X-RateLimit-* headers.
POST /api/platform/auth/register
Creates a user only. Does not create an organization or session.
Body (Zod): { email, password (min 12), name } — email normalized to lowercase.
| Result | Detail |
|---|---|
| 201 | { user: { id, email, name, createdAt } } |
| 409 | Email already registered |
| 400 | Validation failed |
| 429 | Rate limited (per IP) |
POST /api/platform/auth/login
Body (Zod): { email, password }
| Result | Detail |
|---|---|
| 200 | { token, user } |
| 401 | { error: "Invalid credentials" } (same message for unknown email / bad password) |
| 429 | Rate limited (per IP and per email) |
Uses password verify + session create.
POST /api/platform/auth/logout
Bearer optional. Revokes session if present. Always 200 { success: true }.
GET /api/platform/auth/me
Requires valid Bearer session.
200 shape:
{
"user": { "id": "...", "email": "...", "name": "...", "createdAt": "..." },
"organizations": [{ "id": "...", "name": "...", "slug": "...", "createdAt": "..." }],
"projects": [
{
"id": "...",
"organizationId": "...",
"name": "...",
"slug": "...",
"createdAt": "..."
}
]
}401: missing/invalid/expired session.
Never returns passwordHash or token hashes.
POST /api/platform/auth/password
Change password; revokes all sessions.
(See platform auth group in product API summary.)
Session model (product)
| Topic | Detail |
|---|---|
| Password storage | scrypt |
| Session | Opaque bearer token; hashed server-side; limited TTL (~30-day TTL documented in security model) |
| Browser (Closed Beta) | Token may be held in localStorage — XSS critical; CSP enforced; HttpOnly cookies planned, not shipped |
| Password min length | 12 |