8ba32e128c
Replace existing docs with fresh documentation built entirely from source code analysis. OpenAPI 3.1 spec as source of truth, plus human-readable Markdown with curl examples, response samples, and workflow guides. - OpenAPI 3.1 spec covering all 42 endpoints (validated against source) - 7 endpoint reference docs (auth, games, sessions, picker, stats, votes, webhooks) - WebSocket protocol documentation (auth, subscriptions, 4 event types) - 4 guide documents (getting started, session lifecycle, voting, webhooks) - API README with overview, auth docs, and quick reference table - Old docs archived to docs/archive/ Made-with: Cursor
2.8 KiB
2.8 KiB
Auth Endpoints
Simple admin-key authentication. Single role (admin). No user management. Obtain a JWT from POST /api/auth/login and use it as a Bearer token for protected endpoints.
Endpoint Summary
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/auth/login |
No | Exchange admin key for JWT |
| POST | /api/auth/verify |
Bearer | Validate token and return user info |
POST /api/auth/login
Exchange an admin key for a JWT. Use the returned token in the Authorization: Bearer <token> header for protected routes. Tokens expire after 24 hours.
Authentication
None. This endpoint is public.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| key | string | Yes | Admin key (configured via ADMIN_KEY env) |
{
"key": "your-admin-key"
}
Response
200 OK
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"message": "Authentication successful",
"expiresIn": "24h"
}
| Field | Description |
|---|---|
| token | JWT to use in Authorization: Bearer <token> |
| message | Success message |
| expiresIn | Token lifetime |
Error Responses
| Status | Body | When |
|---|---|---|
| 400 | { "error": "Admin key is required" } |
key field missing |
| 401 | { "error": "Invalid admin key" } |
Wrong key |
Example
curl -X POST http://localhost:5000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"key": "your-admin-key"}'
Sample response:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJ0aW1lc3RhbXAiOjE3MTAwMDAwMDAwLCJpYXQiOjE3MTAwMDAwMDB9.abc123",
"message": "Authentication successful",
"expiresIn": "24h"
}
POST /api/auth/verify
Verify that the provided Bearer token is valid and return the decoded user payload.
Authentication
Bearer token required. Include in header: Authorization: Bearer <token>.
Parameters
None.
Response
200 OK
{
"valid": true,
"user": {
"role": "admin",
"timestamp": 1710000000000
}
}
| Field | Description |
|---|---|
| valid | Always true when token is valid |
| user.role | User role (always "admin") |
| user.timestamp | Unix ms when token was issued |
Error Responses
| Status | Body | When |
|---|---|---|
| 401 | { "error": "Access token required" } |
No Authorization header or Bearer token |
| 403 | { "error": "Invalid or expired token" } |
Bad or expired token |
Example
curl -X POST http://localhost:5000/api/auth/verify \
-H "Authorization: Bearer $TOKEN"
Sample response:
{
"valid": true,
"user": {
"role": "admin",
"timestamp": 1710000000000
}
}