{ "openapi": "3.0.0", "paths": { "/health": { "get": { "operationId": "HealthController_check", "parameters": [], "responses": { "200": { "description": "Up, and the database answers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "503": { "description": "Up, but the database doesn’t answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } }, "summary": "Health check", "tags": [ "Health" ] } }, "/api/v1/auth/register": { "post": { "description": "Creates the account and emails a link to verify the address. With REQUIRE_VERIFIED_EMAIL on (the default), the account can log in once the address is verified.", "operationId": "AuthController_register", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } } }, "responses": { "201": { "description": "Created. A verification email is on its way.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" } } } }, "400": { "description": "A field is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "An account already uses this address (`email_taken`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many attempts from this address. Wait a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Create an account", "tags": [ "Auth" ] } }, "/api/v1/auth/verify-email": { "post": { "description": "Takes the token from the link in the verification email. Each token works once, for 24 hours.", "operationId": "AuthController_verifyEmail", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" } } } }, "responses": { "200": { "description": "Verified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "The token is invalid, used or expired (`invalid_token`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many attempts from this address. Wait a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Verify an email address", "tags": [ "Auth" ] } }, "/api/v1/auth/resend-verification": { "post": { "description": "Answers the same whether or not the address has an account, so it can’t be used to find out. The earlier link stops working.", "operationId": "AuthController_resendVerification", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRequest" } } } }, "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "A field is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many attempts from this address. Wait a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Send the verification email again", "tags": [ "Auth" ] } }, "/api/v1/auth/login": { "post": { "description": "Starts a session and returns an access token (short-lived; send it with each request) and a refresh token (long-lived; exchange it at /auth/refresh when the access token expires).", "operationId": "AuthController_login", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Logged in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "400": { "description": "A field is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Wrong email address or password (`invalid_credentials`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The address isn’t verified yet (`email_not_verified`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many attempts from this address. Wait a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Log in", "tags": [ "Auth" ] } }, "/api/v1/auth/refresh": { "post": { "description": "Each refresh token works once: this returns the next one. If a used refresh token is presented again, someone else has a copy, so the whole session is ended (`refresh_token_reused`) and the user logs in again.", "operationId": "AuthController_refresh", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshRequest" } } } }, "responses": { "200": { "description": "A new access token and refresh token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tokens" } } } }, "400": { "description": "A field is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The refresh token is unknown or expired (`refresh_token_invalid`), was already used (`refresh_token_reused`), or its session has ended (`session_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many attempts from this address. Wait a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Exchange a refresh token for a new pair", "tags": [ "Auth" ] } }, "/api/v1/auth/logout": { "post": { "description": "Ends this session. Its access token and refresh token stop working at once.", "operationId": "AuthController_logout", "parameters": [], "responses": { "204": { "description": "Logged out." }, "401": { "description": "No access token, or it has expired, or its session was revoked. Refresh and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Log out", "tags": [ "Auth" ] } }, "/api/v1/auth/logout-all": { "post": { "description": "Ends every session of this account, on every device, this one included.", "operationId": "AuthController_logoutAll", "parameters": [], "responses": { "204": { "description": "Logged out everywhere." }, "401": { "description": "No access token, or it has expired, or its session was revoked. Refresh and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Log out everywhere", "tags": [ "Auth" ] } }, "/api/v1/auth/forgot-password": { "post": { "description": "Answers the same whether or not the address has an account. The link works once, for an hour; asking again replaces it.", "operationId": "AuthController_forgotPassword", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRequest" } } } }, "responses": { "202": { "description": "Accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "A field is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many attempts from this address. Wait a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Email a password-reset link", "tags": [ "Auth" ] } }, "/api/v1/auth/reset-password": { "post": { "description": "Takes the token from the reset email and the new password. Every session of the account ends, and the address counts as verified.", "operationId": "AuthController_resetPassword", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } } } }, "responses": { "204": { "description": "The password is changed. Log in with it." }, "400": { "description": "A field is invalid, or the token is invalid, used or expired (`invalid_token`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many attempts from this address. Wait a minute.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "summary": "Choose a new password", "tags": [ "Auth" ] } }, "/api/v1/users/me": { "get": { "operationId": "UsersController_me", "parameters": [], "responses": { "200": { "description": "The signed-in user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "No access token, or it has expired, or its session was revoked. Refresh and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Your account", "tags": [ "Account" ] }, "patch": { "operationId": "UsersController_update", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileRequest" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "A field is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No access token, or it has expired, or its session was revoked. Refresh and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Change your name", "tags": [ "Account" ] } }, "/api/v1/users/me/password": { "post": { "description": "Needs the current password. Every other session ends; this one stays logged in.", "operationId": "UsersController_changePassword", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } } }, "responses": { "204": { "description": "Changed." }, "400": { "description": "A field is invalid, or the current password is wrong (`wrong_password`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No access token, or it has expired, or its session was revoked. Refresh and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Change your password", "tags": [ "Account" ] } }, "/api/v1/users/me/sessions": { "get": { "description": "Every session that can still be used, newest first, with the one making this request marked `current`.", "operationId": "UsersController_listSessions", "parameters": [], "responses": { "200": { "description": "The sessions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionList" } } } }, "401": { "description": "No access token, or it has expired, or its session was revoked. Refresh and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Where you are logged in", "tags": [ "Account" ] } }, "/api/v1/users/me/sessions/{id}": { "delete": { "description": "Ends one of your sessions: a lost phone, a shared computer.", "operationId": "UsersController_revokeSession", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Ended." }, "401": { "description": "No access token, or it has expired, or its session was revoked. Refresh and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "You have no such session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Log out one device", "tags": [ "Account" ] } }, "/api/v1/admin/users": { "get": { "description": "Newest first, a page at a time, optionally filtered.", "operationId": "AdminController_list", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "From 1.", "schema": { "default": 1, "description": "From 1.", "type": "integer", "minimum": 1 } }, { "name": "pageSize", "required": false, "in": "query", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "search", "required": false, "in": "query", "description": "Part of an email address or a name.", "schema": { "description": "Part of an email address or a name.", "type": "string", "maxLength": 100 } }, { "name": "role", "required": false, "in": "query", "description": "What the user may do.", "schema": { "type": "string", "enum": [ "USER", "ADMIN" ], "description": "What the user may do." } } ], "responses": { "200": { "description": "One page of accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPage" } } } }, "400": { "description": "A field is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No access token, or it has expired, or its session was revoked. Refresh and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The account’s role doesn’t allow this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "List accounts", "tags": [ "Admin" ] } }, "/api/v1/admin/users/{id}/role": { "patch": { "description": "It applies to the account’s next request. You can’t change your own.", "operationId": "AdminController_setRole", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleRequest" } } } }, "responses": { "200": { "description": "Changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "A field is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "No access token, or it has expired, or its session was revoked. Refresh and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not an admin, or it’s your own account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer": [] } ], "summary": "Change an account’s role", "tags": [ "Admin" ] } } }, "info": { "title": "Auth API", "description": "Accounts and sessions for your app: register, verify the email address, log in, refresh, log out, reset a forgotten password, and manage accounts as an admin.\n\n**Authentication.** Log in to get an access token and a refresh token. Send the access token with each request as `Authorization: Bearer `; it lasts minutes. When it expires, exchange the refresh token at `POST /api/v1/auth/refresh` for a new pair. Each refresh token works once: presenting a used one again ends the whole session, because it means someone else has a copy.\n\n**Errors** all have one shape (`ErrorResponse`), with a `code` to branch on.\n\n**Rate limits.** Each address may make a limited number of requests a minute, and fewer to the routes worth guessing at (logging in, registering, the ones that send email). Over the limit, the answer is 429.", "version": "1.0.0", "contact": {} }, "tags": [ { "name": "Auth", "description": "Registering, logging in and out, tokens, and password resets." }, { "name": "Account", "description": "The signed-in user’s own account and sessions." }, { "name": "Admin", "description": "Managing accounts. Admins only." }, { "name": "Health", "description": "For load balancers and uptime checks." } ], "servers": [ { "url": "http://localhost:3000", "description": "Local development" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "schemas": { "RegisterRequest": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 191, "format": "email", "description": "An email address.", "example": "ada@example.com" }, "password": { "type": "string", "minLength": 10, "maxLength": 128, "description": "At least 10 characters.", "example": "correct-horse-battery" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The name to greet the user by.", "example": "Ada Lovelace" } }, "required": [ "email", "password", "name" ] }, "LoginRequest": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 191, "format": "email", "description": "An email address.", "example": "ada@example.com" }, "password": { "type": "string", "minLength": 1, "maxLength": 128, "example": "correct-horse-battery" } }, "required": [ "email", "password" ] }, "RefreshRequest": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 20, "maxLength": 200, "description": "The refresh token from the last login or refresh. Each one works once.", "example": "Vh4k2n8…" } }, "required": [ "refreshToken" ] }, "TokenRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20, "maxLength": 200, "description": "The token from the link in the email.", "example": "q3Bf1cQ9…" } }, "required": [ "token" ] }, "EmailRequest": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 191, "format": "email", "description": "An email address.", "example": "ada@example.com" } }, "required": [ "email" ] }, "ResetPasswordRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20, "maxLength": 200, "description": "The token from the link in the email.", "example": "q3Bf1cQ9…" }, "password": { "type": "string", "minLength": 10, "maxLength": 128, "description": "At least 10 characters.", "example": "correct-horse-battery" } }, "required": [ "token", "password" ] }, "UpdateProfileRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The name to greet the user by.", "example": "Ada Lovelace" } }, "required": [ "name" ] }, "ChangePasswordRequest": { "type": "object", "properties": { "currentPassword": { "type": "string", "minLength": 1, "maxLength": 128, "example": "correct-horse-battery" }, "newPassword": { "type": "string", "minLength": 10, "maxLength": 128, "description": "At least 10 characters.", "example": "correct-horse-battery" } }, "required": [ "currentPassword", "newPassword" ] }, "UpdateRoleRequest": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "USER", "ADMIN" ], "description": "What the user may do." } }, "required": [ "role" ] }, "User": { "type": "object", "properties": { "id": { "type": "string", "example": "cmg3x9k2a0000abcd1234efgh" }, "email": { "type": "string", "maxLength": 191, "format": "email", "description": "An email address.", "example": "ada@example.com" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The name to greet the user by.", "example": "Ada Lovelace" }, "role": { "type": "string", "enum": [ "USER", "ADMIN" ], "description": "What the user may do." }, "emailVerified": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-10-01T09:30:00.000Z" } }, "required": [ "id", "email", "name", "role", "emailVerified", "createdAt" ], "additionalProperties": false, "description": "An account, without anything secret." }, "Tokens": { "type": "object", "properties": { "tokenType": { "type": "string", "enum": [ "Bearer" ] }, "accessToken": { "type": "string", "description": "Send it as `Authorization: Bearer `. A JWT.", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" }, "accessTokenExpiresAt": { "type": "string", "format": "date-time", "example": "2026-10-01T09:30:00.000Z" }, "refreshToken": { "type": "string", "minLength": 20, "maxLength": 200, "description": "The refresh token from the last login or refresh. Each one works once.", "example": "Vh4k2n8…" }, "refreshTokenExpiresAt": { "type": "string", "format": "date-time", "example": "2026-10-01T09:30:00.000Z" } }, "required": [ "tokenType", "accessToken", "accessTokenExpiresAt", "refreshToken", "refreshTokenExpiresAt" ], "additionalProperties": false, "description": "A new pair: use the access token, keep the refresh token." }, "LoginResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "tokens": { "$ref": "#/components/schemas/Tokens" } }, "required": [ "user", "tokens" ], "additionalProperties": false }, "RegisterResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "message": { "type": "string", "example": "Check your email for a link to verify your address." } }, "required": [ "user", "message" ], "additionalProperties": false }, "MessageResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "If an account uses this address, an email is on its way." } }, "required": [ "message" ], "additionalProperties": false }, "Session": { "type": "object", "properties": { "id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-10-01T09:30:00.000Z" }, "lastUsedAt": { "type": "string", "format": "date-time", "example": "2026-10-01T09:30:00.000Z" }, "expiresAt": { "type": "string", "format": "date-time", "example": "2026-10-01T09:30:00.000Z" }, "userAgent": { "nullable": true, "example": "Mozilla/5.0 (iPhone; …)", "type": "string" }, "ip": { "nullable": true, "example": "203.0.113.7", "type": "string" }, "current": { "type": "boolean", "description": "The session this request was made with." } }, "required": [ "id", "createdAt", "lastUsedAt", "expiresAt", "userAgent", "ip", "current" ], "additionalProperties": false }, "SessionList": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } } }, "required": [ "sessions" ], "additionalProperties": false }, "UserPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "items", "page", "pageSize", "total" ], "additionalProperties": false }, "Health": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "database": { "type": "string", "enum": [ "up", "down" ] } }, "required": [ "status", "database" ], "additionalProperties": false }, "ErrorResponse": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 400 }, "error": { "type": "string", "example": "Bad Request" }, "code": { "type": "string", "description": "What went wrong, for programs: validation_failed, invalid_credentials, email_not_verified, email_taken, invalid_token, refresh_token_invalid, refresh_token_reused, session_revoked, wrong_password, unauthorized, forbidden, not_found, rate_limited, internal_error.", "example": "validation_failed" }, "message": { "type": "string", "example": "Some fields are missing or invalid." }, "issues": { "description": "For validation_failed: each field that is wrong.", "example": [ { "path": "password", "message": "Use at least 10 characters." } ], "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "statusCode", "error", "code", "message" ], "additionalProperties": false, "description": "Every error has this shape." } } } }