{ "openapi": "3.1.0", "info": { "title": "Issuary API", "description": "OpenID Connect Provider API", "version": "1.0.0" }, "servers": [ { "url": "/" } ], "components": { "securitySchemes": { "cookieSessionAuth": { "type": "apiKey", "in": "cookie", "name": "session", "description": "Encrypted session cookie issued by Issuary after authentication." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Bearer access token for OAuth 2.0/OIDC protected routes." } } }, "paths": { "/api/admin/me": { "get": { "operationId": "getApiAdminMe", "tags": [ "Admin" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Get current admin", "description": "Get the current admin session identity.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count" ], "description": "UserSession" } }, "required": [ "user" ] } } }, "description": "Success" } } } }, "/api/admin/users": { "get": { "operationId": "getApiAdminUsers", "tags": [ "Admin" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "List admin users", "description": "List users for the admin console.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "Timestamp when the user was soft-deleted" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count", "deleted_at" ], "description": "Admin user information" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "page", "page_size", "total" ] } }, "required": [ "users", "pagination" ], "description": "Admin user list response" } } }, "description": "Success" } }, "parameters": [ { "in": "query", "name": "query", "schema": { "type": "string" } }, { "in": "query", "name": "page", "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "in": "query", "name": "page_size", "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "include_deleted", "schema": { "type": "boolean" } }, { "in": "query", "name": "managed_by", "schema": { "type": "string", "enum": [ "database", "config" ] } }, { "in": "query", "name": "role", "schema": { "type": "string", "enum": [ "user", "admin" ] } } ] }, "post": { "operationId": "postApiAdminUsers", "tags": [ "Admin" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Create admin-managed user", "description": "Create a database-managed user from the admin console.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "Timestamp when the user was soft-deleted" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count", "deleted_at" ], "description": "Admin user information" } }, "required": [ "user" ], "description": "Admin user response" } } }, "description": "Success" }, "201": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "Timestamp when the user was soft-deleted" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count", "deleted_at" ], "description": "Admin user information" } }, "required": [ "user" ], "description": "Admin user response" } } }, "description": "Created" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "FORBIDDEN", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "You do not have permission to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_EDITABLE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This user account cannot be modified.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Forbidden or not editable" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "User not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "EMAIL_ALREADY_EXISTS", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided email is already registered.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Email already exists" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "password": { "type": "string", "minLength": 1, "maxLength": 256, "description": "User's password" }, "role": { "default": "user", "type": "string", "enum": [ "user", "admin" ] }, "email_verified": { "default": false, "type": "boolean" } }, "required": [ "email", "password" ] } } } } } }, "/api/admin/users/{sub}": { "get": { "operationId": "getApiAdminUsersBySub", "tags": [ "Admin" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Get admin user", "description": "Get a user for the admin console.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "Timestamp when the user was soft-deleted" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count", "deleted_at" ], "description": "Admin user information" } }, "required": [ "user" ], "description": "Admin user response" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "FORBIDDEN", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "You do not have permission to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_EDITABLE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This user account cannot be modified.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Forbidden or not editable" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "User not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "EMAIL_ALREADY_EXISTS", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided email is already registered.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Email already exists" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sub", "required": true } ] }, "patch": { "operationId": "patchApiAdminUsersBySub", "tags": [ "Admin" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Update admin-managed user", "description": "Update a database-managed user from the admin console.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "Timestamp when the user was soft-deleted" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count", "deleted_at" ], "description": "Admin user information" } }, "required": [ "user" ], "description": "Admin user response" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "FORBIDDEN", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "You do not have permission to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_EDITABLE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This user account cannot be modified.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Forbidden or not editable" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "User not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "EMAIL_ALREADY_EXISTS", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided email is already registered.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Email already exists" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ] }, "email_verified": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sub", "required": true } ] }, "delete": { "operationId": "deleteApiAdminUsersBySub", "tags": [ "Admin" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Delete admin-managed user", "description": "Soft-delete a database-managed user from the admin console.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" }, "deleted_at": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "Timestamp when the user was soft-deleted" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count", "deleted_at" ], "description": "Admin user information" } }, "required": [ "user" ], "description": "Admin user response" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "FORBIDDEN", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "You do not have permission to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_EDITABLE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This user account cannot be modified.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Forbidden or not editable" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "User not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "EMAIL_ALREADY_EXISTS", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided email is already registered.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Email already exists" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sub", "required": true } ] } }, "/api/auth/accounts": { "get": { "operationId": "getApiAuthAccounts", "tags": [ "Auth" ], "summary": "List remembered accounts", "description": "Lists browser-session remembered accounts available for OIDC account selection.", "responses": { "200": { "description": "Success" } }, "parameters": [ { "in": "query", "name": "client_id", "schema": { "type": "string" } } ] } }, "/api/auth/accounts/select": { "post": { "operationId": "postApiAuthAccountsSelect", "tags": [ "Auth" ], "summary": "Select remembered account", "description": "Promotes a remembered account to the active session user.", "responses": { "200": { "description": "Success" }, "400": { "description": "The account is not remembered in this browser session." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sub": { "type": "string", "minLength": 1 } }, "required": [ "sub" ] } } } } } }, "/api/auth/accounts/remove": { "post": { "operationId": "postApiAuthAccountsRemove", "tags": [ "Auth" ], "summary": "Remove remembered account", "description": "Removes a non-active remembered account from this browser session.", "responses": { "200": { "description": "Success" }, "400": { "description": "The account is active or not remembered." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sub": { "type": "string", "minLength": 1 } }, "required": [ "sub" ] } } } } } }, "/api/auth/2fa/methods": { "get": { "operationId": "getApiAuth2faMethods", "tags": [ "Auth" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Get pending 2FA methods", "description": "Return registered and enabled second factor methods for the pending 2FA session.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "methods": { "type": "array", "items": { "type": "string", "enum": [ "totp", "passkey" ] } } }, "required": [ "methods" ] } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "SECOND_FACTOR_SESSION_EXPIRED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Second factor authentication session has expired. Please login again.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Second factor session expired" } } } }, "/api/auth/login": { "post": { "operationId": "postApiAuthLogin", "tags": [ "Auth" ], "summary": "Login", "description": "Login", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count" ], "description": "Authenticated user session" } }, "required": [ "user" ], "description": "Authentication response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "VALIDATION_ERROR", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided data is invalid.", "description": "Human-readable error message" }, "data": { "type": "string", "description": "Additional error context" } }, "required": [ "code", "message", "data" ] } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "INVALID_EMAIL_OR_PASSWORD", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided email or password is incorrect.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Invalid email or password" }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "EMAIL_VERIFICATION_REQUIRED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Email verification is required before logging in.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Email verification required" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "password": { "type": "string", "minLength": 1, "maxLength": 256, "description": "User's password" } }, "required": [ "email", "password" ] } } } } } }, "/api/auth/logout": { "post": { "operationId": "postApiAuthLogout", "tags": [ "Auth" ], "summary": "Logout", "description": "Logout the current user and purge the session", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true, "description": "Indicates successful operation" } }, "required": [ "ok" ], "description": "OK Response" } } }, "description": "Success" } } } }, "/api/auth/register": { "post": { "operationId": "postApiAuthRegister", "tags": [ "Auth" ], "summary": "Register", "description": "Register a new user with terms consent and send email verification", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count" ], "description": "Authenticated user session" } }, "required": [ "user" ], "description": "Authentication response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "VALIDATION_ERROR", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided data is invalid.", "description": "Human-readable error message" }, "data": { "type": "string", "description": "Additional error context" } }, "required": [ "code", "message", "data" ] } } }, "description": "Validation error" }, "403": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "REGISTRATION_DISABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Public registration is disabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "REGISTRATION_EMAIL_NOT_ALLOWED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This email address is not allowed for registration.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Registration disabled or email not allowed" }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "EMAIL_ALREADY_EXISTS", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided email is already registered.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Email already exists" } }, "parameters": [ { "in": "header", "name": "accept-language", "schema": { "type": "string" }, "description": "Accept-Language header (e.g., \"ko-KR,ko;q=0.9,en;q=0.8\")" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "password": { "type": "string", "minLength": 1, "maxLength": 256, "description": "User's new password" }, "consents": { "description": "Terms consent decisions", "type": "array", "items": { "type": "object", "properties": { "termsId": { "type": "string", "description": "Term ID to consent to" }, "agreed": { "type": "boolean", "description": "Whether user agrees to this term" }, "consentType": { "description": "How consent was obtained. Defaults to term consentMode if omitted", "type": "string", "enum": [ "explicit", "implicit" ] } }, "required": [ "termsId", "agreed" ] } } }, "required": [ "email", "password" ] } } } } } }, "/api/auth/password/forgot": { "post": { "operationId": "postApiAuthPasswordForgot", "tags": [ "Auth" ], "summary": "Request password reset", "description": "Sends a password reset email to the user. Always returns success to prevent email enumeration.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true, "description": "Indicates successful operation" } }, "required": [ "ok" ], "description": "OK Response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "VALIDATION_ERROR", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided data is invalid.", "description": "Human-readable error message" }, "data": { "type": "string", "description": "Additional error context" } }, "required": [ "code", "message", "data" ] } } }, "description": "Validation error" }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "EMAIL_NOT_ACTIVATED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The email service not activated.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Email service not activated" } }, "parameters": [ { "in": "header", "name": "accept-language", "schema": { "type": "string" }, "description": "Accept-Language header (e.g., \"ko-KR,ko;q=0.9,en;q=0.8\")" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" } }, "required": [ "email" ] } } } } } }, "/api/auth/password/reset": { "post": { "operationId": "postApiAuthPasswordReset", "tags": [ "Auth" ], "summary": "Reset password", "description": "Resets the user password using a valid reset token.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" } }, "required": [ "message" ], "description": "Message Response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "INVALID_PASSWORD_RESET_TOKEN", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The password reset token is invalid or has expired.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "VALIDATION_ERROR", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided data is invalid.", "description": "Human-readable error message" }, "data": { "type": "string", "description": "Additional error context" } }, "required": [ "code", "message", "data" ] } ] } } }, "description": "Invalid password reset token or validation error" }, "403": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_EDITABLE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This user account cannot be modified.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "EMAIL_NOT_ACTIVATED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The email service not activated.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "User not editable or email service not activated" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "Token string (verification, reset, or OAuth token)" }, "password": { "type": "string", "minLength": 1, "maxLength": 256, "description": "User's new password" } }, "required": [ "token", "password" ] } } } } } }, "/api/auth/email/verify": { "post": { "operationId": "postApiAuthEmailVerify", "tags": [ "Auth" ], "summary": "Verify Email", "description": "Verify user email with verification token", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count" ], "description": "Authenticated user session" } }, "required": [ "user" ], "description": "Authentication response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "INVALID_VERIFICATION_TOKEN", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The verification token is invalid or has expired.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Invalid verification token" }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "EMAIL_NOT_ACTIVATED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The email service not activated.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Email service not activated" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "Token string (verification, reset, or OAuth token)" } }, "required": [ "token" ] } } } } } }, "/api/auth/email/resend": { "post": { "operationId": "postApiAuthEmailResend", "tags": [ "Auth" ], "summary": "Resend Verification Email", "description": "Resend email verification link to user", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" } }, "required": [ "message" ], "description": "Message Response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "EMAIL_ALREADY_VERIFIED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The email address is already verified.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Email already verified" }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "EMAIL_NOT_ACTIVATED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The email service not activated.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Email service not activated" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "User not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not found" } }, "parameters": [ { "in": "header", "name": "accept-language", "schema": { "type": "string" }, "description": "Accept-Language header (e.g., \"ko-KR,ko;q=0.9,en;q=0.8\")" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" } }, "required": [ "email" ] } } } } } }, "/api/auth/totp/verify": { "post": { "operationId": "postApiAuthTotpVerify", "tags": [ "Auth" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Verify TOTP for login", "description": "Complete login by verifying TOTP code. Requires pending 2FA session from password login.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count" ], "description": "Authenticated user session" } }, "required": [ "user" ], "description": "User session response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "VALIDATION_ERROR", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided data is invalid.", "description": "Human-readable error message" }, "data": { "type": "string", "description": "Additional error context" } }, "required": [ "code", "message", "data" ] } } }, "description": "Validation error or invalid TOTP code" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "SECOND_FACTOR_SESSION_EXPIRED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Second factor authentication session has expired. Please login again.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Second factor session expired" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6, "pattern": "^\\d{6}$", "description": "6-digit TOTP code from authenticator app" } }, "required": [ "code" ] } } } } } }, "/api/auth/totp/recovery/verify": { "post": { "operationId": "postApiAuthTotpRecoveryVerify", "tags": [ "Auth" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Verify TOTP recovery code for login", "description": "Complete login by verifying a one-time TOTP recovery code. Requires pending 2FA session from password login. Each recovery code can only be used once.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count" ], "description": "Authenticated user session" } }, "required": [ "user" ], "description": "User session response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "VALIDATION_ERROR", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided data is invalid.", "description": "Human-readable error message" }, "data": { "type": "string", "description": "Additional error context" } }, "required": [ "code", "message", "data" ] } } }, "description": "Validation error, invalid recovery code, no recovery codes available, or TOTP not enabled" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "SECOND_FACTOR_SESSION_EXPIRED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Second factor authentication session has expired. Please login again.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Second factor session expired" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "description": "One-time recovery code for TOTP (format: XXXX-XXXX-XXXX-XXXX)", "type": "string" } }, "required": [ "code" ] } } } } } }, "/api/auth/passkey/options": { "post": { "operationId": "postApiAuthPasskeyOptions", "tags": [ "Auth" ], "summary": "Get Passkey Authentication Options", "description": "Generate WebAuthn authentication options for passkey login. Supports both passwordless login and 2FA. If a pending 2FA session exists, returns options for that user only.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "WebAuthn authentication options" } }, "required": [ "options" ] } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "PASSKEY_NOT_ENABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Passkey authentication is not enabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Passkey not enabled" } } } }, "/api/auth/passkey/verify": { "post": { "operationId": "postApiAuthPasskeyVerify", "tags": [ "Auth" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Verify Passkey Authentication", "description": "Verify WebAuthn authentication response and create session. Supports both passwordless login and 2FA. If a pending 2FA session exists, verifies the passkey belongs to that user and completes the 2FA flow.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count" ], "description": "Authenticated user session" } }, "required": [ "user" ], "description": "Authentication response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "PASSKEY_NOT_ENABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Passkey authentication is not enabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Passkey not enabled, challenge not found, or verification failed" }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "PASSKEY_USER_MISMATCH", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The passkey does not belong to the pending user.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Passkey user mismatch" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "PASSKEY_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The passkey was not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Passkey not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "object", "properties": { "id": { "type": "string", "description": "Passkey credential ID" }, "rawId": { "type": "string", "description": "Base64URL-encoded string" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string", "description": "Base64URL-encoded string" }, "authenticatorData": { "type": "string", "description": "Base64URL-encoded string" }, "signature": { "type": "string", "description": "Base64URL-encoded string" }, "userHandle": { "type": "string", "description": "Base64URL-encoded string" } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ], "description": "Authenticator assertion response" }, "authenticatorAttachment": { "type": "string", "enum": [ "platform", "cross-platform" ], "description": "Authenticator attachment type" }, "clientExtensionResults": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Client extension results" }, "type": { "type": "string", "const": "public-key", "description": "Public key credential type" } }, "required": [ "id", "rawId", "response", "clientExtensionResults", "type" ], "description": "WebAuthn authentication response" } }, "required": [ "response" ] } } } } } }, "/api/config": { "get": { "operationId": "getApiConfig", "tags": [ "Config" ], "summary": "Get App Config", "description": "Get App Config", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "i18n": { "type": "object", "properties": { "supported_languages": { "type": "array", "items": { "type": "string", "minLength": 2 }, "description": "Languages enabled for this deployment" }, "default_language": { "type": "string", "description": "Default UI language" }, "fallback_language": { "type": "string", "description": "Fallback UI language" } }, "required": [ "supported_languages", "default_language", "fallback_language" ] }, "branding": { "type": "object", "properties": { "background_url": { "description": "Background image URL", "type": "string", "format": "uri" }, "icon_url": { "description": "Icon/logo URL displayed on authentication pages", "type": "string", "format": "uri" }, "title": { "description": "Localized title text for login page", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "subtitle": { "description": "Localized subtitle text for login page", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } } }, "registration": { "type": "object", "properties": { "public_registration": { "type": "boolean", "description": "Whether public self-registration is enabled" }, "email_pattern_filter_enabled": { "type": "boolean", "description": "Whether signup is restricted by configured email filters" }, "email_verification_required": { "type": "boolean", "description": "Whether newly registered users must verify email" }, "signup_notice": { "description": "Localized notice text for implicit consent terms", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "public_registration", "email_pattern_filter_enabled", "email_verification_required" ] }, "database": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether database-backed features are enabled" } }, "required": [ "enabled" ] }, "email": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether email delivery is enabled" } }, "required": [ "enabled" ] }, "admin": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the admin console is enabled" } }, "required": [ "enabled" ] }, "auth": { "type": "object", "properties": { "password": { "type": "object", "properties": { "enabled": { "description": "Whether password-based authentication is enabled.", "anyOf": [ { "type": "boolean" }, { "type": "string" } ] }, "two_factor": { "description": "Two-factor authentication enrollment settings.", "type": "object", "properties": { "enrollment_required": { "description": "Whether password users must enroll a second factor after registration.", "anyOf": [ { "type": "boolean" }, { "type": "string" } ] } }, "additionalProperties": false }, "totp": { "description": "TOTP (Time-based One-Time Password) configuration.", "type": "object", "properties": { "enabled": { "description": "Whether TOTP-based two-factor authentication is enabled.", "anyOf": [ { "type": "boolean" }, { "type": "string" } ] }, "issuer": { "default": "Tinyrack", "description": "Issuer name displayed in authenticator apps for TOTP enrollment.", "type": "string" } }, "additionalProperties": false }, "policy": { "default": { "min_length": 12, "max_length": 256 }, "description": "Password policy settings", "type": "object", "properties": { "min_length": { "default": 12, "description": "Minimum password length.", "type": "integer", "minimum": 1, "maximum": 256 }, "max_length": { "default": 256, "description": "Maximum password length.", "type": "integer", "minimum": -9007199254740991, "maximum": 256 } } } }, "description": "Public password authentication settings" }, "passkey": { "description": "Passkey authentication settings", "type": "object", "properties": { "enabled": { "description": "Whether passkey (WebAuthn) authentication is enabled.", "anyOf": [ { "type": "boolean" }, { "type": "string" } ] }, "rp_id": { "type": "string", "pattern": "^(?!.*:\\/\\/)(?!.*:\\d)(localhost|[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)+)$" }, "origins": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "additionalProperties": false } }, "required": [ "password" ], "description": "Enabled authentication methods" }, "identity_providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider identifier" }, "type": { "type": "string", "enum": [ "github", "google", "apple", "generic_oauth" ], "description": "Provider type" }, "display_name": { "type": "string", "description": "Provider display name" }, "icon_url": { "description": "Provider icon URL", "type": "string", "format": "uri" } }, "required": [ "id", "type", "display_name" ], "description": "OAuth Authentication Method" }, "description": "Enabled external identity providers" }, "account_deletion": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether account deletion is enabled" }, "retention": { "type": "string", "description": "Data retention period after deletion request" } }, "required": [ "enabled", "retention" ] } }, "required": [ "i18n", "branding", "registration", "database", "email", "admin", "auth", "identity_providers", "account_deletion" ] } } }, "description": "Success" } } } }, "/api/consent": { "get": { "operationId": "getApiConsent", "tags": [ "Consent" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Get consent information", "description": "Returns OAuth client information and requested scopes for the consent page.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "OAuth client config/internal ID" }, "clientId": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth client ID" }, "name": { "type": "string", "description": "OAuth client display name" } }, "required": [ "id", "clientId", "name" ], "description": "OAuth client requesting consent" }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Scope name" }, "description": { "type": "string", "description": "Scope description shown to users" } }, "required": [ "name", "description" ], "description": "Consent Scope" }, "description": "Requested OAuth scopes" }, "user": { "type": "object", "properties": { "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" } }, "required": [ "sub", "email" ], "description": "Current user providing consent" } }, "required": [ "client", "scopes", "user" ], "description": "Consent page information" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_CLIENT_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth client was not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "OAuth client not found" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" } }, "parameters": [ { "in": "query", "name": "client_id", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "required": true, "description": "OAuth client ID" }, { "in": "query", "name": "scope", "schema": { "type": "string", "maxLength": 1000 }, "description": "Space-delimited list of OAuth scopes" } ] }, "post": { "operationId": "postApiConsent", "tags": [ "Consent" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Submit consent decision", "description": "Handles the user consent decision for OAuth authorization.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_url": { "type": "string", "format": "uri", "description": "Absolute URL to redirect the user to" } }, "required": [ "redirect_url" ], "description": "Redirect URL Response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_CLIENT_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth client was not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "OAuth client not found" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth client ID" }, "redirect_uri": { "type": "string", "maxLength": 1000, "format": "uri", "description": "OAuth redirect URI" }, "response_type": { "type": "string", "minLength": 1, "maxLength": 100, "description": "OAuth response type (e.g., \"code\", \"token\")" }, "scope": { "type": "string", "maxLength": 1000, "description": "Space-delimited list of OAuth scopes" }, "state": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth state parameter for CSRF protection" }, "nonce": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OIDC nonce for replay attack prevention" }, "code_challenge": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "PKCE code challenge" }, "code_challenge_method": { "type": "string", "enum": [ "S256", "plain" ], "description": "PKCE code challenge method" }, "prompt": { "type": "string", "minLength": 1, "maxLength": 100, "description": "OIDC prompt parameter" }, "max_age": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Maximum authentication age in seconds" }, "reauthenticated": { "type": "string", "const": "1" }, "display": { "type": "string", "enum": [ "page", "popup", "touch", "wap" ], "description": "OIDC display parameter" }, "response_mode": { "type": "string", "enum": [ "query", "fragment", "form_post" ] }, "login_hint": { "type": "string", "minLength": 1, "maxLength": 1000 }, "ui_locales": { "type": "string", "minLength": 1, "maxLength": 1000 }, "id_token_hint": { "type": "string", "minLength": 1, "maxLength": 4000 }, "acr_values": { "type": "string", "minLength": 1, "maxLength": 1000 }, "account_selected": { "type": "string", "const": "1" }, "account_selection_state": { "type": "string", "minLength": 1, "maxLength": 200 }, "decision": { "type": "string", "enum": [ "allow", "deny" ], "description": "User consent decision" } }, "required": [ "client_id", "redirect_uri", "response_type", "decision" ] } } } } } }, "/api/health": { "get": { "operationId": "getApiHealth", "tags": [ "Health" ], "summary": "Health check", "description": "Returns comprehensive health status including uptime and dependency checks.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok", "description": "Overall health status" }, "uptime": { "type": "number", "description": "Uptime in seconds" }, "checks": { "type": "object", "properties": { "database": { "type": "string", "const": "ok", "description": "Database health status" } }, "required": [ "database" ] } }, "required": [ "status", "uptime", "checks" ] } } }, "description": "Healthy" }, "503": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error", "description": "Overall health status" }, "uptime": { "type": "number", "description": "Uptime in seconds" }, "checks": { "type": "object", "properties": { "database": { "type": "string", "enum": [ "ok", "error" ], "description": "Database health status" } }, "required": [ "database" ] }, "error": { "description": "Optional failure reason", "type": "string" } }, "required": [ "status", "uptime", "checks" ] } } }, "description": "Unhealthy" } } } }, "/api/health/ready": { "get": { "operationId": "getApiHealthReady", "tags": [ "Health" ], "summary": "Readiness probe", "description": "Returns 200 if the server is ready to accept traffic. Checks database connectivity.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok", "description": "Readiness status" }, "checks": { "type": "object", "properties": { "database": { "type": "string", "const": "ok", "description": "Database readiness status" } }, "required": [ "database" ] } }, "required": [ "status", "checks" ] } } }, "description": "Ready" }, "503": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "error", "description": "Readiness status" }, "checks": { "type": "object", "properties": { "database": { "type": "string", "enum": [ "ok", "error" ], "description": "Database readiness status" } }, "required": [ "database" ] }, "error": { "description": "Optional failure reason", "type": "string" } }, "required": [ "status", "checks" ] } } }, "description": "Not ready" } } } }, "/api/health/live": { "get": { "operationId": "getApiHealthLive", "tags": [ "Health" ], "summary": "Liveness probe", "description": "Returns 200 if the server is alive. Used by Kubernetes liveness probe.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok", "description": "Liveness status" } }, "required": [ "status" ] } } }, "description": "Alive" } } } }, "/api/terms": { "get": { "operationId": "getApiTerms", "tags": [ "Terms" ], "security": [ { "cookieSessionAuth": [] }, {} ], "summary": "Get terms of service", "description": "Returns list of terms with consent mode and user consent status. If user is authenticated, includes their consent history.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "terms": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the term" }, "required": { "type": "boolean", "description": "Whether this term is mandatory" }, "consentMode": { "type": "string", "enum": [ "explicit", "implicit" ], "description": "Consent mode: explicit (checkbox required) or implicit (auto-agree)" }, "version": { "type": "string", "description": "Version of the term" }, "effectiveDate": { "description": "When this version became effective", "type": "string" }, "title": { "type": "string", "description": "Localized title" }, "type": { "type": "string", "enum": [ "link", "text" ], "description": "How to interpret the content" }, "content": { "type": "string", "description": "Content value (URL if type=link, text if type=text)" }, "userConsent": { "anyOf": [ { "type": "object", "properties": { "agreed": { "type": "boolean", "description": "Whether the user agreed to this term" }, "agreedVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Version of the term the user agreed to" }, "agreedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ], "description": "When the user agreed to the term" }, "consentType": { "anyOf": [ { "type": "string", "enum": [ "explicit", "implicit" ] }, { "type": "null" } ], "description": "How consent was obtained" }, "requiresUpdate": { "type": "boolean", "description": "Whether the user needs to re-consent due to version change" } }, "required": [ "agreed", "agreedVersion", "agreedAt", "consentType", "requiresUpdate" ], "description": "User consent status" }, { "type": "null" } ], "description": "User consent status (null if not logged in)" } }, "required": [ "id", "required", "consentMode", "version", "title", "type", "content", "userConsent" ], "description": "Term item with user consent" }, "description": "List of terms" }, "pendingTerms": { "type": "array", "items": { "type": "string" }, "description": "Term IDs that require consent" } }, "required": [ "terms", "pendingTerms" ], "description": "Terms response" } } }, "description": "Success" } }, "parameters": [ { "in": "query", "name": "lang", "schema": { "default": "en", "type": "string", "minLength": 2, "maxLength": 10 }, "description": "Language code for localized content" } ] } }, "/api/terms/consent": { "post": { "operationId": "postApiTermsConsent", "tags": [ "Terms" ], "security": [ { "cookieSessionAuth": [] }, {} ], "summary": "Submit terms consent", "description": "Record user consent decisions for terms of service. Required terms must be agreed to. For pending OAuth registration, this also completes user registration.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "recorded": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of consents recorded" }, "registered": { "description": "True if OAuth registration was completed with this consent submission", "type": "boolean" } }, "required": [ "ok", "recorded" ], "description": "Terms consent response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "VALIDATION_ERROR", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided data is invalid.", "description": "Human-readable error message" }, "data": { "type": "string", "description": "Additional error context" } }, "required": [ "code", "message", "data" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_SESSION_EXPIRED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth session has expired. Please start the login process again.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Validation error or OAuth session expired" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "REGISTRATION_EMAIL_NOT_ALLOWED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This email address is not allowed for registration.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Registration email not allowed" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "consents": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "termsId": { "type": "string", "description": "Term ID to consent to" }, "agreed": { "type": "boolean", "description": "Whether user agrees to this term" }, "consentType": { "description": "How consent was obtained. Defaults to term consentMode if omitted", "type": "string", "enum": [ "explicit", "implicit" ] } }, "required": [ "termsId", "agreed" ] }, "description": "List of consent decisions" }, "registrationToken": { "description": "Pending OAuth registration token. Required when completing registration after terms consent.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "consents" ], "description": "Terms consent request" } } } } } }, "/api/user": { "delete": { "operationId": "deleteApiUser", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Delete Account", "description": "Request account deletion. The account will be soft-deleted and permanently removed after the configured retention period.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "deleted_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Timestamp when deletion was requested" }, "permanent_deletion_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Timestamp when permanent deletion will occur" } }, "required": [ "ok", "deleted_at", "permanent_deletion_at" ] } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "ACCOUNT_ALREADY_DELETED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This account has already been deleted.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Account already deleted" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "ACCOUNT_DELETION_DISABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Account deletion is not enabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_EDITABLE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This user account cannot be modified.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Account deletion disabled or user not editable" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "User not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not found" } } } }, "/api/user/session": { "get": { "operationId": "getApiUserSession", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] }, {} ], "summary": "Get Session", "description": "Get Session", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count" ], "description": "UserSession" } } } } }, "description": "Success" } } } }, "/api/user/password": { "post": { "operationId": "postApiUserPassword", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Set Password", "description": "Set a password for users who signed up via OAuth. Only works if no password is currently set.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true, "description": "Indicates successful operation" } }, "required": [ "ok" ], "description": "OK Response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "VALIDATION_ERROR", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided data is invalid.", "description": "Human-readable error message" }, "data": { "type": "string", "description": "Additional error context" } }, "required": [ "code", "message", "data" ] } } }, "description": "Password authentication disabled or validation error" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_EDITABLE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This user account cannot be modified.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not editable" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "User not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not found" }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "PASSWORD_ALREADY_SET", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "A password is already set for this account. Use password change instead.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Password already set" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "minLength": 1, "maxLength": 256, "description": "User's new password" } }, "required": [ "password" ] } } } } }, "put": { "operationId": "putApiUserPassword", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Change Password", "description": "Change password for users who already have a password set. Requires current password verification.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true, "description": "Indicates successful operation" } }, "required": [ "ok" ], "description": "OK Response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "PASSWORD_NOT_SET", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "No password is set for this account.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "VALIDATION_ERROR", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided data is invalid.", "description": "Human-readable error message" }, "data": { "type": "string", "description": "Additional error context" } }, "required": [ "code", "message", "data" ] } ] } } }, "description": "Password not set or password auth disabled" }, "401": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "INVALID_CURRENT_PASSWORD", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The current password is incorrect.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Unauthorized or invalid current password" }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_EDITABLE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This user account cannot be modified.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not editable" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "User not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "current_password": { "type": "string", "minLength": 1, "maxLength": 256, "description": "User's password" }, "new_password": { "type": "string", "minLength": 1, "maxLength": 256, "description": "User's new password" } }, "required": [ "current_password", "new_password" ] } } } } }, "delete": { "operationId": "deleteApiUserPassword", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Remove Password", "description": "Remove password for users who have at least one OAuth account linked. Requires current password verification and at least one OAuth account.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true, "description": "Indicates successful operation" } }, "required": [ "ok" ], "description": "OK Response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "PASSWORD_NOT_SET", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "No password is set for this account.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "CANNOT_REMOVE_LAST_AUTH_METHOD", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Cannot remove password. You need at least one way to log in.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "CANNOT_REMOVE_PASSWORD_WITH_SECOND_FACTOR_ONLY", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Cannot remove password when 2FA (TOTP/Passkey) is set up without OAuth. Add an OAuth account first, or disable 2FA before removing password.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "VALIDATION_ERROR", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided data is invalid.", "description": "Human-readable error message" }, "data": { "type": "string", "description": "Additional error context" } }, "required": [ "code", "message", "data" ] } ] } } }, "description": "Password not set, password auth disabled, cannot remove last auth method, or cannot remove password with second factor only" }, "401": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "INVALID_CURRENT_PASSWORD", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The current password is incorrect.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Unauthorized or invalid current password" }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_EDITABLE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This user account cannot be modified.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not editable" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "User not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "current_password": { "type": "string", "minLength": 1, "maxLength": 256, "description": "User's password" } }, "required": [ "current_password" ] } } } } } }, "/api/user/oauth-accounts": { "get": { "operationId": "getApiUserOauthAccounts", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "List Linked OAuth Accounts", "description": "Returns all OAuth accounts linked to the current user", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "provider_name": { "type": "string", "minLength": 1, "description": "OAuth provider identifier" }, "linked_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Timestamp when the provider account was linked" } }, "required": [ "provider_name", "linked_at" ], "description": "Linked OAuth Account" }, "description": "OAuth accounts currently linked to the user" }, "available_providers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider identifier" }, "display_name": { "type": "string", "description": "Provider display name" }, "icon_url": { "description": "Provider icon URL", "type": "string", "format": "uri" }, "linked": { "type": "boolean", "description": "Whether this provider is linked to the current user" } }, "required": [ "id", "display_name", "linked" ], "description": "Available OAuth Provider" }, "description": "Configured providers with linked state" } }, "required": [ "accounts", "available_providers" ], "description": "Linked OAuth accounts response" } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "User not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not found" } } } }, "/api/user/totp/setup": { "post": { "operationId": "postApiUserTotpSetup", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Start TOTP Setup", "description": "Generate a new TOTP secret and QR code for authenticator app setup. Call verify endpoint after user scans the QR code to complete setup.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "description": "TOTP secret key (base32 encoded)" }, "otpauth_url": { "type": "string", "description": "OTPAuth URL for authenticator apps" }, "qr_code": { "type": "string", "description": "QR code as data URL" } }, "required": [ "secret", "otpauth_url", "qr_code" ] } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "VALIDATION_ERROR", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided data is invalid.", "description": "Human-readable error message" }, "data": { "type": "string", "description": "Additional error context" } }, "required": [ "code", "message", "data" ] } } }, "description": "Validation error (for example when TOTP is disabled)" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "SECOND_FACTOR_NOT_ALLOWED_FOR_CONFIG_USER", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Second factor authentication is not available for config-managed users.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Second factor not allowed for config user" }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "TOTP_ALREADY_ENABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "TOTP is already enabled for this account.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "TOTP already enabled" } } } }, "/api/user/totp/verify": { "post": { "operationId": "postApiUserTotpVerify", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Verify TOTP Setup", "description": "Verify the TOTP code from authenticator app. Must call setup endpoint first to get the QR code. Returns one-time recovery codes. Call confirm endpoint after user acknowledges saving the recovery codes to complete setup.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "recovery_codes": { "type": "array", "items": { "type": "string" }, "description": "One-time recovery codes (shown only once, store securely)" } }, "required": [ "recovery_codes" ] } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "TOTP_NOT_SETUP", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "TOTP setup has not been initiated. Please start setup first.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "TOTP not setup or invalid TOTP code" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "TOTP_ALREADY_ENABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "TOTP is already enabled for this account.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "TOTP already enabled" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6, "pattern": "^\\d{6}$", "description": "6-digit TOTP code from authenticator app" } }, "required": [ "code" ] } } } } } }, "/api/user/totp/confirm": { "post": { "operationId": "postApiUserTotpConfirm", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Confirm TOTP Setup", "description": "Confirm that recovery codes have been saved to complete TOTP setup. Must call verify endpoint first to get recovery codes. This endpoint completes the TOTP setup and enables 2FA.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count" ], "description": "Authenticated user session" } }, "required": [ "user" ], "description": "User session response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "TOTP_NOT_SETUP", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "TOTP setup has not been initiated. Please start setup first.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "TOTP not setup" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "TOTP_ALREADY_ENABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "TOTP is already enabled for this account.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "TOTP already enabled" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": {} }, { "type": "null" } ] } } } } } }, "/api/user/totp/recovery/regenerate": { "post": { "operationId": "postApiUserTotpRecoveryRegenerate", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Regenerate TOTP recovery codes", "description": "Generate a new set of single-use TOTP recovery codes for a user with fully enabled TOTP.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "recovery_codes": { "type": "array", "items": { "type": "string" }, "description": "One-time recovery codes (shown only once, store securely)" } }, "required": [ "recovery_codes" ] } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "INVALID_TOTP_CODE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The provided TOTP code is invalid.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "TOTP_NOT_ENABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "TOTP is not enabled for this account.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "TOTP not enabled or invalid TOTP code" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6, "pattern": "^\\d{6}$", "description": "6-digit TOTP code from authenticator app" } }, "required": [ "code" ] } } } } } }, "/api/user/totp": { "delete": { "operationId": "deleteApiUserTotp", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Disable TOTP", "description": "Disable TOTP two-factor authentication for the current user. Requires a valid TOTP code from the authenticator app.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true, "description": "Indicates successful operation" } }, "required": [ "ok" ], "description": "OK Response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "TOTP_NOT_ENABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "TOTP is not enabled for this account.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "TOTP not enabled, invalid code, or cannot remove last second factor" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "SECOND_FACTOR_NOT_ALLOWED_FOR_CONFIG_USER", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Second factor authentication is not available for config-managed users.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Second factor not allowed for config user" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6, "pattern": "^\\d{6}$", "description": "6-digit TOTP code from authenticator app" } }, "required": [ "code" ] } } } } } }, "/api/user/passkeys": { "get": { "operationId": "getApiUserPasskeys", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Get Passkeys", "description": "Get all passkeys for the current user", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "passkeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "Passkey record UUID" }, "credential_id": { "type": "string", "description": "Passkey credential ID" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-defined passkey name" }, "device_type": { "type": "string", "enum": [ "singleDevice", "multiDevice" ], "description": "Passkey device type" }, "backed_up": { "type": "boolean", "description": "Whether the credential is synced/backed up" }, "created_at": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Timestamp when the passkey was created" } }, "required": [ "id", "credential_id", "name", "device_type", "backed_up", "created_at" ], "description": "Passkey information" } } }, "required": [ "passkeys" ] } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "PASSKEY_NOT_ENABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Passkey authentication is not enabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Passkey authentication is disabled" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" } } } }, "/api/user/passkeys/{id}": { "delete": { "operationId": "deleteApiUserPasskeysById", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Delete Passkey", "description": "Delete a passkey by ID", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true, "description": "Indicates successful operation" } }, "required": [ "ok" ], "description": "OK Response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "PASSKEY_NOT_ENABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Passkey authentication is not enabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Passkey not enabled, cannot remove last passkey, or cannot remove last second factor" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "SECOND_FACTOR_NOT_ALLOWED_FOR_CONFIG_USER", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Second factor authentication is not available for config-managed users.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Second factor not allowed for config user" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "PASSKEY_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The passkey was not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Passkey not found" } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true, "description": "Entity UUID" } ] }, "patch": { "operationId": "patchApiUserPasskeysById", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Rename Passkey", "description": "Rename a passkey", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true, "description": "Indicates successful operation" } }, "required": [ "ok" ], "description": "OK Response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "PASSKEY_NOT_ENABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Passkey authentication is not enabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Passkey not enabled" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "PASSKEY_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The passkey was not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Passkey not found" } }, "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "required": true, "description": "Entity UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Passkey display name" } }, "required": [ "name" ] } } } } } }, "/api/user/passkeys/register/options": { "post": { "operationId": "postApiUserPasskeysRegisterOptions", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Get Passkey Registration Options", "description": "Generate WebAuthn registration options for registering a new passkey. Accepts both full user session and pending 2FA setup session.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "options": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "WebAuthn registration options" } }, "required": [ "options" ] } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "PASSKEY_NOT_ENABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Passkey authentication is not enabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Passkey not enabled" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "SECOND_FACTOR_NOT_ALLOWED_FOR_CONFIG_USER", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Second factor authentication is not available for config-managed users.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Second factor not allowed for config user" } } } }, "/api/user/passkeys/register/verify": { "post": { "operationId": "postApiUserPasskeysRegisterVerify", "tags": [ "User" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Verify Passkey Registration", "description": "Verify and complete passkey registration. Accepts both full user session and pending 2FA setup session.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true, "description": "Whether passkey verification succeeded" }, "user": { "description": "User session if passkey setup was completed from pending setup state", "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count" ] }, "second_factor_setup_completed": { "type": "boolean", "description": "Whether this request completed the mandatory 2FA setup flow" } }, "required": [ "ok", "second_factor_setup_completed" ] } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "PASSKEY_NOT_ENABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Passkey authentication is not enabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Passkey not enabled, challenge not found, or verification failed" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "409": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "PASSKEY_ALREADY_EXISTS", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This passkey is already registered.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Passkey already exists" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "WebAuthn registration response" }, "name": { "description": "Optional name for the passkey", "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "response" ] } } } } } }, "/api/oauth/authorization-context": { "get": { "operationId": "getApiOauthAuthorizationContext", "tags": [ "OAuth" ], "summary": "Get authorization request context", "description": "Returns validated OAuth client and scope information for login and registration screens.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "OAuth client config/internal ID" }, "clientId": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth client ID" }, "name": { "type": "string", "description": "OAuth client display name" } }, "required": [ "id", "clientId", "name" ], "description": "Consent Client Information" }, "redirect_uri": { "type": "string", "maxLength": 1000, "format": "uri", "description": "Validated OAuth redirect URI" }, "redirect_origin": { "type": "string", "format": "uri", "description": "Origin extracted from the validated redirect URI" }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Scope name" }, "description": { "type": "string", "description": "Scope description shown to users" } }, "required": [ "name", "description" ], "description": "Consent Scope" }, "description": "Validated requested OAuth scopes with descriptions" } }, "required": [ "client", "redirect_uri", "redirect_origin", "scopes" ], "description": "Authorization context shown before authentication" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_CLIENT_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth client was not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_CLIENT_DISABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth client is disabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "INVALID_REDIRECT_URI", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The redirect URI is not registered for this client.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "UNSUPPORTED_RESPONSE_TYPE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The response type is not supported for this client.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "INVALID_SCOPE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "One or more requested scopes are invalid.", "description": "Human-readable error message" }, "data": { "type": "object", "properties": { "invalidScopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "invalidScopes" ], "description": "Additional error context" } }, "required": [ "code", "message", "data" ] } ] } } }, "description": "Invalid authorization request context" } }, "parameters": [ { "in": "query", "name": "client_id", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "required": true, "description": "OAuth client ID" }, { "in": "query", "name": "redirect_uri", "schema": { "type": "string", "maxLength": 1000, "format": "uri" }, "required": true, "description": "OAuth redirect URI" }, { "in": "query", "name": "response_type", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "required": true, "description": "OAuth response type (e.g., \"code\", \"token\")" }, { "in": "query", "name": "scope", "schema": { "type": "string", "maxLength": 1000 }, "description": "Space-delimited list of OAuth scopes" } ] } }, "/api/oauth/{provider}/authorize": { "get": { "operationId": "getApiOauthByProviderAuthorize", "tags": [ "OAuth Connect" ], "security": [ { "cookieSessionAuth": [] }, {} ], "summary": "Initiate OAuth Authorize Flow", "description": "Redirects the user to the OAuth provider for authentication", "responses": { "302": { "description": "Redirect to OAuth provider" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_PROVIDER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth provider is not configured or is disabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "OAuth provider not found" } }, "parameters": [ { "in": "path", "name": "provider", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "OAuth provider name (e.g., \"google\", \"github\")" }, { "in": "query", "name": "mode", "schema": { "default": "login", "type": "string", "enum": [ "login", "register", "link" ] }, "description": "OAuth connect mode" }, { "in": "query", "name": "return_url", "schema": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": "Return URL or path to redirect after completion" } ] } }, "/api/oauth/{provider}/callback": { "get": { "operationId": "getApiOauthByProviderCallback", "tags": [ "OAuth Connect" ], "summary": "OAuth Callback", "description": "Handles the callback from OAuth provider after user authorization", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count" ], "description": "Authenticated user session" }, "is_new_user": { "type": "boolean", "description": "Whether this callback created a new user account" }, "return_url": { "description": "Optional return URL after OAuth flow completion", "type": "string" } }, "required": [ "user", "is_new_user" ], "description": "OAuth callback response" } } }, "description": "Success" }, "302": { "description": "Redirect" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_STATE_MISMATCH", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth state parameter does not match. Please try again.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_INVALID_REQUEST", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Missing required parameters: code and state.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_SESSION_EXPIRED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth session has expired. Please start the login process again.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "State mismatch, session expired, or invalid request" }, "403": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_EMAIL_NOT_VERIFIED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The email address from the OAuth provider is not verified.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "REGISTRATION_EMAIL_NOT_ALLOWED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This email address is not allowed for registration.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Email not verified or registration email not allowed" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_PROVIDER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth provider is not configured or is disabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "OAuth provider not found" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_EMAIL_CONFLICT", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "An account with this email already exists. Please link your account instead.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_ACCOUNT_ALREADY_LINKED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This OAuth account is already linked to another user.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Email conflict or account already linked" }, "502": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_TOKEN_EXCHANGE_FAILED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Failed to exchange authorization code for tokens.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_USERINFO_FAILED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Failed to fetch user information from OAuth provider.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Token exchange failed or user info failed" } }, "parameters": [ { "in": "path", "name": "provider", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "OAuth provider name (e.g., \"google\", \"github\")" }, { "in": "query", "name": "code", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": "OAuth authorization code" }, { "in": "query", "name": "state", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": "OAuth state parameter for CSRF protection" }, { "in": "query", "name": "error", "schema": { "type": "string" } }, { "in": "query", "name": "error_description", "schema": { "type": "string" } } ] }, "post": { "operationId": "postApiOauthByProviderCallback", "tags": [ "OAuth Connect" ], "summary": "OAuth Callback (POST)", "description": "Handles the form_post callback from OAuth providers like Apple", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "managed_by": { "type": "string", "enum": [ "database", "config" ], "description": "User data source (database or static config)" }, "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "User subject identifier" }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "User email address" }, "role": { "type": "string", "enum": [ "user", "admin" ], "description": "User role" }, "email_verified": { "type": "boolean", "description": "Whether the user's email is verified" }, "email_verification_required": { "type": "boolean", "description": "Whether email verification is required for the user" }, "has_password": { "type": "boolean", "description": "Whether the user has a password set" }, "totp_registered": { "type": "boolean", "description": "Whether TOTP is registered for the user" }, "totp_recovery_codes_missing": { "type": "boolean", "description": "Whether the user has no usable TOTP recovery codes left" }, "second_factor_required": { "type": "boolean", "description": "Whether the user is required to use 2FA (e.g., due to policy)" }, "passkey_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of passkeys registered for the user" } }, "required": [ "managed_by", "sub", "email", "role", "email_verified", "email_verification_required", "has_password", "totp_registered", "totp_recovery_codes_missing", "second_factor_required", "passkey_count" ], "description": "Authenticated user session" }, "is_new_user": { "type": "boolean", "description": "Whether this callback created a new user account" }, "return_url": { "description": "Optional return URL after OAuth flow completion", "type": "string" } }, "required": [ "user", "is_new_user" ], "description": "OAuth callback response" } } }, "description": "Success" }, "302": { "description": "Redirect" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_STATE_MISMATCH", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth state parameter does not match. Please try again.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_INVALID_REQUEST", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Missing required parameters: code and state.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_SESSION_EXPIRED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth session has expired. Please start the login process again.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "State mismatch, session expired, or invalid request" }, "403": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_EMAIL_NOT_VERIFIED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The email address from the OAuth provider is not verified.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "REGISTRATION_EMAIL_NOT_ALLOWED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This email address is not allowed for registration.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Email not verified or registration email not allowed" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_PROVIDER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth provider is not configured or is disabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "OAuth provider not found" }, "409": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_EMAIL_CONFLICT", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "An account with this email already exists. Please link your account instead.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_ACCOUNT_ALREADY_LINKED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "This OAuth account is already linked to another user.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Email conflict or account already linked" }, "502": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_TOKEN_EXCHANGE_FAILED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Failed to exchange authorization code for tokens.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_USERINFO_FAILED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Failed to fetch user information from OAuth provider.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Token exchange failed or user info failed" } }, "parameters": [ { "in": "path", "name": "provider", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "OAuth provider name (e.g., \"google\", \"github\")" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth authorization code" }, "state": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth state parameter for CSRF protection" }, "error": { "type": "string" }, "error_description": { "type": "string" } }, "description": "OAuth provider callback payload" } } } } } }, "/api/oauth/{provider}": { "delete": { "operationId": "deleteApiOauthByProvider", "tags": [ "OAuth Connect" ], "security": [ { "cookieSessionAuth": [] } ], "summary": "Unlink OAuth Account", "description": "Unlinks an OAuth provider from the current user", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true, "description": "Indicates successful operation" } }, "required": [ "ok" ], "description": "OK Response" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "CANNOT_UNLINK_LAST_AUTH_METHOD", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Cannot unlink the last authentication method. You need at least one way to log in.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Cannot unlink last auth method" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "UNAUTHORIZED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Authentication is required to access this resource.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_PROVIDER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth provider is not configured or is disabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "OAuth provider not found, account not linked, or user not found" } }, "parameters": [ { "in": "path", "name": "provider", "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "OAuth provider name (e.g., \"google\", \"github\")" } ] } }, "/oauth/authorize": { "get": { "operationId": "getOauthAuthorize", "tags": [ "OpenID" ], "security": [ { "cookieSessionAuth": [] }, {} ], "summary": "Authorize", "description": "OAuth2 Authorization Endpoint", "responses": { "302": { "description": "Redirect" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "OAuth/OIDC error code" }, "error_description": { "type": "string", "description": "Human-readable error description" } }, "required": [ "error", "error_description" ], "description": "OAuth Error Response" } } }, "description": "OAuth error" } }, "parameters": [ { "in": "query", "name": "response_type", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "required": true, "description": "OAuth response type (e.g., \"code\", \"token\")" }, { "in": "query", "name": "redirect_uri", "schema": { "type": "string", "maxLength": 1000, "format": "uri" }, "required": true, "description": "OAuth redirect URI" }, { "in": "query", "name": "state", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": "OAuth state parameter for CSRF protection" }, { "in": "query", "name": "client_id", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "required": true, "description": "OAuth client ID" }, { "in": "query", "name": "code_challenge", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": "PKCE code challenge" }, { "in": "query", "name": "code_challenge_method", "schema": { "type": "string", "enum": [ "S256", "plain" ] }, "description": "PKCE code challenge method" }, { "in": "query", "name": "scope", "schema": { "type": "string", "maxLength": 1000 }, "description": "Space-delimited list of OAuth scopes" }, { "in": "query", "name": "nonce", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": "OIDC nonce for replay attack prevention" }, { "in": "query", "name": "prompt", "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "OIDC prompt parameter" }, { "in": "query", "name": "max_age", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "description": "Maximum authentication age in seconds" }, { "in": "query", "name": "reauthenticated", "schema": { "type": "string", "const": "1" } }, { "in": "query", "name": "account_selected", "schema": { "type": "string", "const": "1" } }, { "in": "query", "name": "account_selection_state", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "in": "query", "name": "display", "schema": { "type": "string", "enum": [ "page", "popup", "touch", "wap" ] }, "description": "OIDC display parameter" }, { "in": "query", "name": "response_mode", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "in": "query", "name": "login_hint", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 } }, { "in": "query", "name": "ui_locales", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 } }, { "in": "query", "name": "id_token_hint", "schema": { "type": "string", "minLength": 1, "maxLength": 4000 } }, { "in": "query", "name": "acr_values", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 } } ] } }, "/oauth/device_authorization": { "post": { "operationId": "postOauthDeviceAuthorization", "tags": [ "OpenID" ], "summary": "Device Authorization", "description": "OAuth 2.0 Device Authorization endpoint", "responses": { "200": { "description": "Device authorization response" }, "401": { "description": "Invalid client credentials" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "client_id": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth client ID" }, "client_secret": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth client secret" }, "scope": { "type": "string", "maxLength": 1000, "description": "Space-delimited list of OAuth scopes" } }, "description": "OAuth2 device authorization request payload" } } } } } }, "/oauth/device": { "get": { "operationId": "getOauthDevice", "tags": [ "OpenID" ], "summary": "Device Verification", "description": "User-facing OAuth device verification page", "responses": { "200": { "description": "Device verification form" } } }, "post": { "operationId": "postOauthDevice", "tags": [ "OpenID" ], "summary": "Approve Device Authorization", "description": "Approves a pending OAuth device authorization request", "responses": { "200": { "description": "Device authorization approved" }, "400": { "description": "Invalid device user code" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "user_code": { "type": "string", "minLength": 1, "maxLength": 64 }, "decision": { "default": "approve", "type": "string", "enum": [ "approve", "deny" ] } }, "required": [ "user_code" ] } } } } } }, "/oauth/end_session": { "get": { "operationId": "getOauthEndSession", "tags": [ "OpenID" ], "summary": "End Session", "description": "RP-initiated logout endpoint", "responses": { "302": { "description": "Redirect after logout" }, "400": { "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "OAuth/OIDC error code" }, "error_description": { "type": "string", "description": "Human-readable error description" } }, "required": [ "error", "error_description" ], "description": "OAuth Error Response" } } }, "description": "Invalid logout request" } }, "parameters": [ { "in": "query", "name": "client_id", "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "post_logout_redirect_uri", "schema": { "type": "string", "format": "uri" } }, { "in": "query", "name": "id_token_hint", "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "state", "schema": { "type": "string", "minLength": 1 } } ] } }, "/oauth/token": { "post": { "operationId": "postOauthToken", "tags": [ "OpenID" ], "summary": "Token", "description": "OAuth2 Token Endpoint - Exchange authorization code or refresh token for access tokens (RFC 6749)", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "OAuth 2.0 access token (JWT)" }, "token_type": { "type": "string", "const": "Bearer", "description": "OAuth token type" }, "expires_in": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Access token lifetime in seconds" }, "refresh_token": { "description": "Refresh token", "type": "string" }, "id_token": { "description": "OpenID Connect ID token (JWT)", "type": "string" }, "scope": { "type": "string", "description": "Space-separated granted scopes" } }, "required": [ "access_token", "token_type", "expires_in", "scope" ] } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_CLIENT_DISABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth client is disabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "MISSING_AUTHORIZATION_CODE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Missing authorization code.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "MISSING_REDIRECT_URI", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Missing redirect_uri.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "MISSING_REFRESH_TOKEN", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Missing refresh_token.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "MISSING_DEVICE_CODE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Missing device_code.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "UNSUPPORTED_GRANT_TYPE", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Grant type is not supported.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "Bad request, unsupported grant type, missing parameters, or disabled client" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "INVALID_CLIENT_CREDENTIALS", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Invalid client credentials.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Invalid client credentials" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "minLength": 1, "maxLength": 200 }, "code": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth authorization code" }, "redirect_uri": { "type": "string", "maxLength": 1000, "format": "uri", "description": "OAuth redirect URI" }, "client_id": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth client ID" }, "client_secret": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth client secret" }, "code_verifier": { "type": "string", "minLength": 43, "maxLength": 128, "pattern": "^[A-Za-z0-9._~-]+$", "description": "PKCE code verifier (43-128 characters)" }, "refresh_token": { "type": "string", "minLength": 1, "description": "Token string (verification, reset, or OAuth token)" }, "scope": { "type": "string", "maxLength": 1000, "description": "Space-delimited list of OAuth scopes" }, "device_code": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "description": "OAuth2 token request payload" } } } } } }, "/oauth/introspect": { "post": { "operationId": "postOauthIntrospect", "tags": [ "OpenID" ], "summary": "Token Introspection", "description": "OAuth2 Token Introspection Endpoint - Returns metadata about tokens (RFC 7662)", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Whether the token is currently active" }, "scope": { "description": "Space-separated list of scopes", "type": "string" }, "client_id": { "description": "OAuth client identifier", "type": "string" }, "token_type": { "description": "OAuth token type", "type": "string", "const": "Bearer" }, "exp": { "description": "Expiration timestamp (seconds)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "iat": { "description": "Issued-at timestamp (seconds)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sub": { "description": "Subject identifier", "type": "string" }, "iss": { "description": "Token issuer URL", "type": "string", "format": "uri" } }, "required": [ "active" ] } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_CLIENT_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth client was not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_CLIENT_DISABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth client is disabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "OAuth client not found or disabled" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "INVALID_CLIENT_CREDENTIALS", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Invalid client credentials.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Invalid client credentials" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "Token string (verification, reset, or OAuth token)" }, "token_type_hint": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Hint about the type of token" }, "client_id": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth client ID" }, "client_secret": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth client secret" } }, "required": [ "token" ], "description": "OAuth2 token introspection request payload" } } } } } }, "/oauth/revoke": { "post": { "operationId": "postOauthRevoke", "tags": [ "OpenID" ], "summary": "Token Revocation", "description": "OAuth 2.0 Token Revocation Endpoint - Revokes access or refresh tokens (RFC 7009)", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": {}, "description": "Token revoked successfully or token was already invalid." } } }, "description": "Token revoked" }, "400": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_CLIENT_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth client was not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] }, { "type": "object", "properties": { "code": { "type": "string", "const": "OAUTH_CLIENT_DISABLED", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "The OAuth client is disabled.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } ] } } }, "description": "OAuth client not found or disabled" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "INVALID_CLIENT_CREDENTIALS", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Invalid client credentials.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Invalid client credentials" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "description": "Token string (verification, reset, or OAuth token)" }, "token_type_hint": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Hint about the type of token" }, "client_id": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth client ID" }, "client_secret": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "OAuth client secret" } }, "required": [ "token" ], "description": "OAuth2 token revocation request payload" } } } } } }, "/oauth/userinfo": { "get": { "operationId": "getOauthUserinfo", "tags": [ "OpenID" ], "security": [ { "bearerAuth": [] } ], "summary": "User Info", "description": "OIDC UserInfo Endpoint - Returns claims about the authenticated user (RFC OIDC Core ยง5.3)", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Subject identifier" }, "email": { "description": "User email address", "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "email_verified": { "description": "Whether the email address is verified", "type": "boolean" }, "name": { "description": "Display name", "type": "string" }, "picture": { "description": "Profile picture URL", "type": "string", "format": "uri" }, "preferred_username": { "description": "Preferred username", "type": "string" } }, "required": [ "sub" ] } } }, "description": "Success" }, "401": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "MISSING_AUTHORIZATION_HEADER", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "Missing Authorization header.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "Missing or invalid authorization header" }, "404": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "const": "USER_NOT_FOUND", "description": "Machine-readable error code" }, "message": { "type": "string", "const": "User not found.", "description": "Human-readable error message" } }, "required": [ "code", "message" ] } } }, "description": "User not found" } }, "parameters": [ { "in": "header", "name": "authorization", "schema": { "type": "string", "minLength": 1 }, "description": "Bearer token: \"Bearer \"" } ] }, "post": { "operationId": "postOauthUserinfo", "tags": [ "OpenID" ], "security": [ { "bearerAuth": [] } ], "summary": "User Info", "description": "OIDC UserInfo Endpoint POST method", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sub": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Subject identifier" }, "email": { "description": "User email address", "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "email_verified": { "description": "Whether the email address is verified", "type": "boolean" }, "name": { "description": "Display name", "type": "string" }, "picture": { "description": "Profile picture URL", "type": "string", "format": "uri" }, "preferred_username": { "description": "Preferred username", "type": "string" } }, "required": [ "sub" ] } } }, "description": "Success" } }, "parameters": [ { "in": "header", "name": "authorization", "schema": { "type": "string", "minLength": 1 }, "description": "Bearer token: \"Bearer \"" } ] } }, "/oauth/.well-known/jwks": { "get": { "operationId": "getOauthWellKnownJwks", "tags": [ "OpenID" ], "summary": "JWKS", "description": "JSON Web Key Set (JWKS) endpoint - Returns RSA public keys used for verifying tokens (RFC 7517). Supports automatic key rotation with multiple active keys.", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "kty": { "type": "string", "description": "Key Type" }, "use": { "type": "string", "description": "Public Key Use" }, "kid": { "type": "string", "description": "Key ID" }, "alg": { "type": "string", "description": "Algorithm" }, "n": { "description": "RSA modulus", "type": "string" }, "e": { "description": "RSA exponent", "type": "string" }, "x": { "description": "EC x coordinate", "type": "string" }, "y": { "description": "EC y coordinate", "type": "string" }, "crv": { "description": "EC curve name", "type": "string" } }, "required": [ "kty", "use", "kid", "alg" ] }, "description": "Array of JWK objects representing public keys for token verification" } }, "required": [ "keys" ] } } }, "description": "JWKS response" } } } }, "/oauth/.well-known/openid-configuration": { "get": { "operationId": "getOauthWellKnownOpenidConfiguration", "tags": [ "OpenID" ], "summary": "OpenID Provider Configuration", "description": "Returns OpenID Provider Configuration Information (OpenID Connect Discovery 1.0)", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string", "description": "URL using the https scheme with no query or fragment component" }, "authorization_endpoint": { "type": "string", "description": "URL of the OP's OAuth 2.0 Authorization Endpoint" }, "token_endpoint": { "type": "string", "description": "URL of the OP's OAuth 2.0 Token Endpoint" }, "jwks_uri": { "type": "string", "description": "URL of the OP's JSON Web Key Set document" }, "response_types_supported": { "type": "array", "items": { "type": "string" }, "description": "JSON array containing a list of the OAuth 2.0 response_type values" }, "response_modes_supported": { "description": "JSON array containing a list of supported response_mode values", "type": "array", "items": { "type": "string" } }, "subject_types_supported": { "type": "array", "items": { "type": "string" }, "description": "JSON array containing a list of the Subject Identifier types" }, "id_token_signing_alg_values_supported": { "type": "array", "items": { "type": "string" }, "description": "JSON array containing a list of the JWS signing algorithms supported" }, "userinfo_endpoint": { "description": "URL of the OP's UserInfo Endpoint", "type": "string" }, "scopes_supported": { "description": "JSON array containing a list of the OAuth 2.0 scope values", "type": "array", "items": { "type": "string" } }, "claims_supported": { "description": "JSON array containing a list of the Claim Names", "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "description": "JSON array containing a list of the OAuth 2.0 Grant Type values", "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "description": "JSON array containing a list of Client Authentication methods", "type": "array", "items": { "type": "string" } }, "introspection_endpoint_auth_methods_supported": { "description": "JSON array containing a list of Token Introspection Client Authentication methods", "type": "array", "items": { "type": "string" } }, "revocation_endpoint_auth_methods_supported": { "description": "JSON array containing a list of Token Revocation Client Authentication methods", "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "description": "JSON array containing a list of PKCE code challenge methods", "type": "array", "items": { "type": "string" } }, "introspection_endpoint": { "description": "URL of the OP's OAuth 2.0 Token Introspection Endpoint", "type": "string" }, "revocation_endpoint": { "description": "URL of the OP's OAuth 2.0 Token Revocation Endpoint", "type": "string" }, "service_documentation": { "description": "URL of a page containing human-readable information", "type": "string" }, "ui_locales_supported": { "description": "Languages and scripts supported for the user interface", "type": "array", "items": { "type": "string" } }, "request_parameter_supported": { "description": "Whether request object by value is supported", "type": "boolean" }, "request_uri_parameter_supported": { "description": "Whether request object by reference is supported", "type": "boolean" }, "claims_parameter_supported": { "description": "Whether the claims request parameter is supported", "type": "boolean" } }, "required": [ "issuer", "authorization_endpoint", "token_endpoint", "jwks_uri", "response_types_supported", "subject_types_supported", "id_token_signing_alg_values_supported" ] } } }, "description": "OpenID Configuration" } } } } } }