{ "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "Nhost Authentication API", "description": "Comprehensive authentication service for managing user identities, sessions, and authentication methods", "license": { "name": "MIT License", "url": "https://opensource.org/licenses/MIT" }, "contact": { "name": "Nhost Support", "url": "https://nhost.io" } }, "servers": [ { "url": "https://{subdomain}.auth.{region}.nhost.run/v1", "description": "Nhost Authentication API Server" } ], "tags": [ { "name": "authentication", "description": "User authentication operations including sign-in, sign-up, and various authentication methods (email/password, passwordless, OAuth, WebAuthn, MFA)" }, { "name": "security", "description": "Security-related operations including Personal Access Tokens, WebAuthn management, account elevation, and account linking" }, { "name": "session", "description": "Session management operations including token refresh, verification, and sign-out" }, { "name": "user", "description": "User profile and account management operations including email/password changes, MFA configuration, and profile updates" }, { "name": "system", "description": "System operations including health checks, service version, and public key endpoints" }, { "name": "verification", "description": "Email and ticket verification operations for confirming user actions" }, { "name": "excludeme", "description": "These operations are not intended to be used directly by clients and should be excluded from client SDKs" } ], "paths": { "/.well-known/jwks.json": { "get": { "summary": "Get public keys for JWT verification in JWK Set format", "description": "Retrieve the JSON Web Key Set (JWKS) containing public keys used to verify JWT signatures. This endpoint is used by clients to validate access tokens.", "operationId": "getJWKs", "tags": [ "system" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JWKSet" } } }, "description": "The public keys in JWK Set format" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/elevate": { "get": { "summary": "Get available elevation methods", "description": "List the authenticated user's available elevation methods, whether elevation is required under the configured mode, and whether the current session is elevated.", "operationId": "getElevationMethods", "tags": [ "security" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevationMethodsResponse" } } }, "description": "Available elevation methods" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/elevate/webauthn": { "post": { "summary": "Elevate access for an already signed in user using FIDO2 Webauthn", "description": "Generate a Webauthn challenge for elevating user permissions", "operationId": "elevateWebauthn", "tags": [ "security" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKeyCredentialRequestOptions" } } }, "description": "Challenge sent for elevation" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/elevate/webauthn/verify": { "post": { "summary": "Verify FIDO2 Webauthn authentication using public-key cryptography for elevation", "description": "Complete Webauthn elevation by verifying the authentication response", "operationId": "verifyElevateWebauthn", "tags": [ "security" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "WebAuthn credential assertion response for elevation verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInWebauthnVerifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPayload" } } }, "description": "Elevated successfully" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/elevate/totp": { "post": { "summary": "Elevate access for an already signed in user using TOTP MFA", "description": "Verify a TOTP code to elevate the permissions of an already signed in user", "operationId": "elevateTotp", "tags": [ "security" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "TOTP code for elevation verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevateTotpRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPayload" } } }, "description": "Elevated successfully" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/elevate/otp/email": { "post": { "summary": "Request a one-time password by email to elevate an already signed in user", "description": "Send a one-time password to the signed in user's email address to start elevation", "operationId": "elevateOTPEmail", "tags": [ "security" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } }, "description": "One-time password sent successfully" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/elevate/otp/email/verify": { "post": { "summary": "Elevate access for an already signed in user using a one-time password sent by email", "description": "Verify a one-time password sent by email to elevate the permissions of an already signed in user", "operationId": "verifyElevateOTPEmail", "tags": [ "security" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "One-time password for elevation verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevateOTPEmailVerifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPayload" } } }, "description": "Elevated successfully" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/elevate/otp/sms": { "post": { "summary": "Request a one-time password by SMS to elevate an already signed in user", "description": "Send a one-time password to the signed in user's verified phone number to start elevation", "operationId": "elevateOTPSms", "tags": [ "security" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } }, "description": "One-time password sent successfully" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/elevate/otp/sms/verify": { "post": { "summary": "Elevate access for an already signed in user using a one-time password sent by SMS", "description": "Verify a one-time password sent by SMS to elevate the permissions of an already signed in user", "operationId": "verifyElevateOTPSms", "tags": [ "security" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "One-time password for elevation verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElevateOTPSmsVerifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPayload" } } }, "description": "Elevated successfully" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/healthz": { "get": { "summary": "Health check (GET)", "description": "Verify if the authentication service is operational using GET method", "operationId": "healthCheckGet", "tags": [ "system" ], "responses": { "200": { "description": "Service is healthy and operational", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } }, "head": { "summary": "Health check (HEAD)", "description": "Verify if the authentication service is operational using HEAD method", "operationId": "healthCheckHead", "tags": [ "system" ], "responses": { "200": { "description": "Service is healthy and operational" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/link/idtoken": { "post": { "summary": "Link a user account with the provider's account using an id token", "description": "Link the authenticated user's account with an external OAuth provider account using an ID token. Requires elevated permissions.", "operationId": "linkIdToken", "tags": [ "security" ], "security": [ { "BearerAuthElevated": [] } ], "requestBody": { "description": "ID token and provider information for account linking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkIdTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Identity linked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/mfa/totp/generate": { "get": { "summary": "Generate TOTP secret", "description": "Generate a Time-based One-Time Password (TOTP) secret for setting up multi-factor authentication", "operationId": "changeUserMfa", "tags": [ "user" ], "security": [ { "BearerAuthElevated": [] } ], "responses": { "200": { "description": "TOTP secret successfully generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpGenerateResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/pat": { "post": { "summary": "Create a Personal Access Token (PAT)", "description": "Generate a new Personal Access Token for programmatic API access. PATs are long-lived tokens that can be used instead of regular authentication for automated systems. Requires elevated permissions.", "operationId": "createPAT", "tags": [ "security" ], "security": [ { "BearerAuthElevated": [] } ], "requestBody": { "description": "Personal Access Token creation request with expiration and metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePATRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePATResponse" } } }, "description": "Successfully created a Personal Access Token" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/anonymous": { "post": { "summary": "Sign in anonymously", "description": "Create an anonymous user session without providing credentials. Anonymous users can be converted to regular users later via the deanonymize endpoint.\nThis endpoint always creates a new user and is **not** gated by `AUTH_DISABLE_AUTO_SIGNUP`; it is controlled by `AUTH_DISABLE_SIGNUP` and `AUTH_ANONYMOUS_USERS_ENABLED`.\n", "operationId": "signInAnonymous", "tags": [ "authentication" ], "requestBody": { "description": "Optional user profile information for anonymous sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInAnonymousRequest" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPayload" } } }, "description": "Successfully signed in" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/email-password": { "post": { "summary": "Sign in with email and password", "description": "Authenticate a user with their email and password. Returns a session object or MFA challenge if two-factor authentication is enabled.", "operationId": "signInEmailPassword", "tags": [ "authentication" ], "requestBody": { "description": "User credentials for email and password authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInEmailPasswordRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInEmailPasswordResponse" } } }, "description": "Authentication successful. If MFA is enabled, a challenge will be returned instead of a session." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/idtoken": { "post": { "summary": "Sign in with an ID token", "description": "Authenticate using an ID token from a supported OAuth provider (Apple or Google).\nIf the user doesn't exist and `AUTH_DISABLE_AUTO_SIGNUP` is not set, a new account will be created.\nWhen `AUTH_DISABLE_AUTO_SIGNUP` is enabled, users must use the `/signup/idtoken` endpoint to register first.\n", "operationId": "signInIdToken", "tags": [ "authentication" ], "requestBody": { "description": "ID token and provider information for authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInIdTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Successfully signed in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPayload" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/mfa/totp": { "post": { "summary": "Verify TOTP for MFA", "description": "Complete the multi-factor authentication by verifying a Time-based One-Time Password (TOTP). Returns a session if validation is successful.", "operationId": "verifySignInMfaTotp", "tags": [ "authentication" ], "requestBody": { "description": "MFA ticket and TOTP code for multi-factor authentication verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInMfaTotpRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPayload" } } }, "description": "MFA verification successful, session created" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/otp/email": { "post": { "summary": "Sign in with email OTP", "description": "Initiate email-based one-time password authentication. Sends an OTP to the specified email address.\nIf the user doesn't exist and `AUTH_DISABLE_AUTO_SIGNUP` is not set, a new account will be created with the provided options.\nWhen `AUTH_DISABLE_AUTO_SIGNUP` is enabled, users must use the `/signup/otp/email` endpoint to register first.\n", "operationId": "signInOTPEmail", "tags": [ "authentication" ], "requestBody": { "description": "Email address and optional user options for OTP authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInOTPEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "OTP sent to the user's email. To prevent account enumeration, this response is also returned without side effects when the email is not registered and `AUTH_DISABLE_AUTO_SIGNUP` is enabled.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/otp/email/verify": { "post": { "summary": "Verify email OTP", "description": "Complete email OTP authentication by verifying the one-time password. Returns a session if validation is successful.", "operationId": "verifySignInOTPEmail", "tags": [ "authentication" ], "requestBody": { "description": "OTP code and email address for verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInOTPEmailVerifyRequest" } } }, "required": true }, "responses": { "200": { "description": "Magic link sent to user's email successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInOTPEmailVerifyResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/passwordless/email": { "post": { "summary": "Sign in with magic link email", "description": "Initiate passwordless authentication by sending a magic link to the user's email.\nIf the user doesn't exist and `AUTH_DISABLE_AUTO_SIGNUP` is not set, a new account will be created with the provided options.\nWhen `AUTH_DISABLE_AUTO_SIGNUP` is enabled, users must use the `/signup/passwordless/email` endpoint to register first.\n", "operationId": "signInPasswordlessEmail", "tags": [ "authentication" ], "requestBody": { "description": "Email address and optional user options for magic link authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInPasswordlessEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "Magic link sent to the user's email. To prevent account enumeration, this response is also returned without side effects when the email is not registered and `AUTH_DISABLE_AUTO_SIGNUP` is enabled.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/passwordless/sms": { "post": { "operationId": "signInPasswordlessSms", "summary": "Sign in with SMS OTP", "description": "Initiate passwordless authentication by sending a one-time password to the user's phone number.\nIf the user doesn't exist and `AUTH_DISABLE_AUTO_SIGNUP` is not set, a new account will be created with the provided options.\nWhen `AUTH_DISABLE_AUTO_SIGNUP` is enabled, users must use the `/signup/passwordless/sms` endpoint to register first.\n", "tags": [ "authentication" ], "requestBody": { "description": "Phone number and optional user options for SMS OTP authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInPasswordlessSmsRequest" } } }, "required": true }, "responses": { "200": { "description": "OTP sent to the user's phone number. To prevent account enumeration, this response is also returned without side effects when the phone number is not registered and `AUTH_DISABLE_AUTO_SIGNUP` is enabled.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/passwordless/sms/otp": { "post": { "operationId": "verifySignInPasswordlessSms", "summary": "Verify SMS OTP and complete authentication", "description": "Complete passwordless SMS authentication by verifying the one-time password and returning a session.", "tags": [ "authentication" ], "requestBody": { "description": "Phone number and OTP code for SMS verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInPasswordlessSmsOtpRequest" } } }, "required": true }, "responses": { "200": { "description": "User successfully authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInPasswordlessSmsOtpResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/pat": { "post": { "summary": "Sign in with Personal Access Token (PAT)", "description": "Authenticate using a Personal Access Token. PATs are long-lived tokens that can be used for programmatic access to the API.", "operationId": "signInPAT", "tags": [ "authentication" ], "requestBody": { "description": "Personal Access Token for authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInPATRequest" } } }, "required": true }, "responses": { "200": { "description": "Successfully signed in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPayload" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/provider/{provider}": { "get": { "summary": "Sign in with an OAuth2 provider", "description": "Initiate OAuth2 authentication flow with a social provider. Redirects the user to the provider's authorization page.\nIf the user doesn't exist and `AUTH_DISABLE_AUTO_SIGNUP` is not set, a new account will be created upon callback.\nWhen `AUTH_DISABLE_AUTO_SIGNUP` is enabled, users must use the `/signup/provider/{provider}` endpoint to register first.\n", "operationId": "signInProvider", "tags": [ "authentication" ], "parameters": [ { "$ref": "#/components/parameters/SignInProvider" }, { "name": "allowedRoles", "in": "query", "required": false, "description": "Array of allowed roles for the user", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "me", "user" ] } }, { "name": "defaultRole", "in": "query", "required": false, "description": "Default role for the user", "schema": { "type": "string", "example": "user" } }, { "name": "displayName", "in": "query", "required": false, "description": "Display name for the user", "schema": { "type": "string", "pattern": "^[\\p{L}\\p{N}\\p{S} ,.'-]+$", "maxLength": 32, "example": "John Smith" } }, { "name": "locale", "in": "query", "required": false, "description": "A two or three characters locale", "schema": { "type": "string", "maxLength": 3, "minLength": 2, "example": "en" } }, { "name": "metadata", "in": "query", "required": false, "description": "Additional metadata for the user (JSON encoded string)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "example": { "firstName": "John", "lastName": "Smith" } } } } }, { "name": "redirectTo", "in": "query", "required": false, "description": "URI to redirect to", "schema": { "type": "string", "format": "uri", "example": "https://my-app.com/catch-redirection" } }, { "name": "connect", "in": "query", "required": false, "description": "If set, this means that the user is already authenticated and wants to link their account. This needs to be a valid JWT access token.", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Opaque state value to be returned by the provider", "schema": { "type": "string" } }, { "name": "providerSpecificParams", "in": "query", "required": false, "description": "Additional provider-specific parameters", "style": "form", "explode": true, "schema": { "$ref": "#/components/schemas/ProviderSpecificParams" } }, { "name": "upstreamParams", "in": "query", "required": false, "description": "Extra parameters forwarded to the upstream OAuth2 provider's authorization URL. Reserved OAuth2/OIDC parameters are rejected.", "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/UpstreamAuthParams" } }, { "name": "codeChallenge", "in": "query", "required": false, "description": "PKCE code challenge (S256). When provided, the callback redirect will contain an authorization code instead of a refresh token.", "schema": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "responses": { "302": { "description": "Redirect to social provider", "headers": { "Location": { "$ref": "#/components/headers/RedirectLocation" } }, "content": {} }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/provider/{provider}/callback": { "get": { "summary": "OAuth2 provider callback endpoint", "description": "Handles the callback from OAuth2 providers after user authorization. Processes the authorization code and creates a user session.\nThis endpoint is where the signin-vs-signup decision (from the signed `flow` state claim) and the `AUTH_DISABLE_AUTO_SIGNUP` gate are actually enforced: on a `flow=signin` state with an unknown user and the flag enabled, the user is redirected with `error=invalid-email-password`; on a `flow=signup` state with an existing user, the user is redirected with `error=user-already-exists`.\n", "operationId": "signInProviderCallbackGet", "tags": [ "authentication", "excludeme" ], "parameters": [ { "$ref": "#/components/parameters/SignInProvider" }, { "name": "code", "in": "query", "description": "Authorization code provided by the authentication provider", "schema": { "type": "string" } }, { "name": "id_token", "in": "query", "description": "ID token provided by the authentication provider", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "description": "State parameter to avoid CSRF attacks", "schema": { "type": "string" } }, { "name": "oauth_token", "in": "query", "required": false, "description": "OAuth token for the provider (e.g., X)", "schema": { "type": "string" } }, { "name": "oauth_verifier", "in": "query", "required": false, "description": "OAuth verifier for the provider (e.g., X)", "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "description": "Error message if authentication failed", "schema": { "type": "string" } }, { "name": "error_description", "in": "query", "required": false, "description": "Detailed error description if authentication failed", "schema": { "type": "string" } }, { "name": "error_uri", "in": "query", "required": false, "description": "URI with more information about the error", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to client application after successful authentication", "headers": { "Location": { "$ref": "#/components/headers/RedirectLocation" } }, "content": {} }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } }, "post": { "summary": "OAuth2 provider callback endpoint (form_post)", "description": "Handles OAuth2 provider callbacks using form_post response mode. Used by providers like Apple that send data via POST instead of query parameters.\nLike the GET variant, this endpoint enforces the signin-vs-signup decision carried by the signed `flow` state claim and the `AUTH_DISABLE_AUTO_SIGNUP` gate.\n", "operationId": "signInProviderCallbackPost", "tags": [ "authentication", "excludeme" ], "parameters": [ { "$ref": "#/components/parameters/SignInProvider" } ], "requestBody": { "description": "OAuth2 provider callback data including authorization code, ID token, and state", "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "code": { "type": "string", "nullable": true, "description": "Authorization code provided by the authentication provider" }, "id_token": { "type": "string", "nullable": true, "description": "ID token provided by the authentication provider" }, "state": { "type": "string", "description": "State parameter to avoid CSRF attacks" }, "user": { "type": "string", "nullable": true, "description": "JSON string containing user information (only provided on first authentication with Apple)" }, "error": { "type": "string", "nullable": true, "description": "Error message if authentication failed" }, "error_description": { "type": "string", "nullable": true, "description": "Detailed error description if authentication failed" }, "error_uri": { "type": "string", "nullable": true, "description": "URI with more information about the error" } }, "required": [ "state" ], "additionalProperties": true } } } }, "responses": { "302": { "description": "Redirect to client application after successful authentication", "headers": { "Location": { "$ref": "#/components/headers/RedirectLocation" } }, "content": {} }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/provider/{provider}/callback/tokens": { "get": { "summary": "Retrieve OAuth2 provider tokens from callback", "description": "After successful OAuth2 authentication, retrieve the provider session containing access token, refresh token, and expiration information for the specified provider. To ensure the data isn't stale this endpoint must be called immediately after the OAuth callback to obtain the tokens. The session is cleared from the database during this call, so subsequent calls will fail without going through the sign-in flow again. It is the user's responsibility to store the session safely (e.g., in browser local storage).", "operationId": "getProviderTokens", "tags": [ "authentication" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SignInProvider" } ], "responses": { "200": { "description": "Successfully retrieved provider session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSession" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signin/webauthn": { "post": { "summary": "Sign in with Webauthn", "description": "Initiate a Webauthn sign-in process by sending a challenge to the user's device. The user must have previously registered a Webauthn credential.", "operationId": "signInWebauthn", "requestBody": { "description": "Optional email address to help identify the user for WebAuthn authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInWebauthnRequest" } } }, "required": false }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKeyCredentialRequestOptions" } } }, "description": "Challenge sent" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } }, "tags": [ "authentication" ] } }, "/signin/webauthn/verify": { "post": { "summary": "Verify Webauthn sign-in", "description": "Complete the Webauthn sign-in process by verifying the response from the user's device. Returns a session if validation is successful.", "operationId": "verifySignInWebauthn", "requestBody": { "description": "WebAuthn credential assertion response from the user's authenticator device", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInWebauthnVerifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPayload" } } }, "description": "Sign in successful" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } }, "tags": [ "authentication" ] } }, "/signout": { "post": { "summary": "Sign out", "description": "End the current user session by invalidating refresh tokens. Optionally sign out from all devices.", "operationId": "signOut", "tags": [ "session" ], "security": [ { "BearerAuth": [] }, {} ], "requestBody": { "description": "Sign-out options including refresh token and whether to sign out from all devices", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignOutRequest" } } } }, "responses": { "200": { "description": "Successfully signed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signup/email-password": { "post": { "summary": "Sign up with email and password", "description": "Register a new user account with email and password. Returns a session if email verification is not required, otherwise returns null session.", "operationId": "signUpEmailPassword", "tags": [ "authentication" ], "requestBody": { "description": "User registration information including email, password, and optional profile data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUpEmailPasswordRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPayload" } } }, "description": "Registration successful. If email verification is required, session will be null." }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signup/webauthn": { "post": { "summary": "Sign up with Webauthn", "description": "Initiate a Webauthn sign-up process by sending a challenge to the user's device. The user must not have an existing account.", "operationId": "signUpWebauthn", "requestBody": { "description": "Email address and optional user options for WebAuthn registration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUpWebauthnRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKeyCredentialCreationOptions" } } }, "description": "Challenge sent" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } }, "tags": [ "authentication" ] } }, "/signup/webauthn/verify": { "post": { "summary": "Verify Webauthn sign-up", "description": "Complete the Webauthn sign-up process by verifying the response from the user's device. Returns a session if validation is successful.", "operationId": "verifySignUpWebauthn", "requestBody": { "description": "WebAuthn credential creation response and optional user profile information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUpWebauthnVerifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPayload" } } }, "description": "Sign up successful" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } }, "tags": [ "authentication", "verification" ] } }, "/signup/passwordless/email": { "post": { "summary": "Sign up with magic link email", "description": "Register a new user account using passwordless email authentication. Sends a magic link to the specified email address for verification.\nUse this endpoint to explicitly register a new account. When `AUTH_DISABLE_AUTO_SIGNUP` is enabled, this is the only way to register through this method.\n", "operationId": "signUpPasswordlessEmail", "tags": [ "authentication" ], "requestBody": { "description": "Email address and optional user options for magic link registration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUpPasswordlessEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "Magic link sent to the user's email. To prevent account enumeration, this response is also returned without side effects when the email is already registered.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signup/otp/email": { "post": { "summary": "Sign up with email OTP", "description": "Register a new user account using email OTP authentication. Sends a one-time password to the specified email address.\nUse this endpoint to explicitly register a new account. When `AUTH_DISABLE_AUTO_SIGNUP` is enabled, this is the only way to register through this method.\n", "operationId": "signUpOTPEmail", "tags": [ "authentication" ], "requestBody": { "description": "Email address and optional user options for OTP registration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUpOTPEmailRequest" } } }, "required": true }, "responses": { "200": { "description": "OTP sent to the user's email. To prevent account enumeration, this response is also returned without side effects when the email is already registered.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signup/passwordless/sms": { "post": { "summary": "Sign up with SMS OTP", "description": "Register a new user account using SMS OTP authentication. Sends a one-time password to the specified phone number.\nUse this endpoint to explicitly register a new account. When `AUTH_DISABLE_AUTO_SIGNUP` is enabled, this is the only way to register through this method.\n", "operationId": "signUpPasswordlessSms", "tags": [ "authentication" ], "requestBody": { "description": "Phone number and optional user options for SMS OTP registration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUpPasswordlessSmsRequest" } } }, "required": true }, "responses": { "200": { "description": "OTP sent to the user's phone number. To prevent account enumeration, this response is also returned without side effects when the phone number is already registered.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signup/idtoken": { "post": { "summary": "Sign up with ID token", "description": "Register a new user account using an ID token from Apple or Google.\nUse this endpoint to explicitly register a new account. When `AUTH_DISABLE_AUTO_SIGNUP` is enabled, this is the only way to register through this method.\nIf the user already exists, a `user-already-exists` error is returned.\n", "operationId": "signUpIdToken", "tags": [ "authentication" ], "requestBody": { "description": "ID token and provider information for registration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUpIdTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Successfully signed up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPayload" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/signup/provider/{provider}": { "get": { "summary": "Sign up with OAuth provider", "description": "Initiate OAuth signup flow with the specified provider. Redirects to the provider's authorization page.\nUse this endpoint to explicitly register a new account. When `AUTH_DISABLE_AUTO_SIGNUP` is enabled, this is the only way to register through this method.\nIf the user already exists at callback time, they are redirected with `error=user-already-exists`.\n", "operationId": "signUpProvider", "tags": [ "authentication" ], "parameters": [ { "$ref": "#/components/parameters/SignInProvider" }, { "name": "allowedRoles", "in": "query", "required": false, "description": "Array of allowed roles for the user", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "me", "user" ] } }, { "name": "defaultRole", "in": "query", "required": false, "description": "Default role for the user", "schema": { "type": "string", "example": "user" } }, { "name": "displayName", "in": "query", "required": false, "description": "Display name for the user", "schema": { "type": "string", "pattern": "^[\\p{L}\\p{N}\\p{S} ,.'-]+$", "maxLength": 32, "example": "John Smith" } }, { "name": "locale", "in": "query", "required": false, "description": "A two or three characters locale", "schema": { "type": "string", "maxLength": 3, "minLength": 2, "example": "en" } }, { "name": "metadata", "in": "query", "required": false, "description": "Additional metadata for the user (JSON encoded string)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "example": { "firstName": "John", "lastName": "Smith" } } } } }, { "name": "redirectTo", "in": "query", "required": false, "description": "URI to redirect to", "schema": { "type": "string", "format": "uri", "example": "https://my-app.com/catch-redirection" } }, { "name": "state", "in": "query", "required": false, "description": "Opaque state value to be returned by the provider", "schema": { "type": "string" } }, { "name": "providerSpecificParams", "in": "query", "required": false, "description": "Additional provider-specific parameters", "style": "form", "explode": true, "schema": { "$ref": "#/components/schemas/ProviderSpecificParams" } }, { "name": "upstreamParams", "in": "query", "required": false, "description": "Extra parameters forwarded to the upstream OAuth2 provider's authorization URL. Reserved OAuth2/OIDC parameters are rejected.", "style": "deepObject", "explode": true, "schema": { "$ref": "#/components/schemas/UpstreamAuthParams" } }, { "name": "codeChallenge", "in": "query", "required": false, "description": "PKCE code challenge (S256). When provided, the callback redirect will contain an authorization code instead of a refresh token.", "schema": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "responses": { "302": { "description": "Redirect to social provider", "headers": { "Location": { "$ref": "#/components/headers/RedirectLocation" } }, "content": {} }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/token": { "post": { "summary": "Refresh access token", "description": "Generate a new JWT access token using a valid refresh token. The refresh token used will be revoked and a new one will be issued.", "operationId": "refreshToken", "tags": [ "session" ], "requestBody": { "description": "Refresh token to exchange for a new access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "description": "Access token successfully refreshed" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/token/provider/{provider}": { "post": { "summary": "Refresh OAuth2 provider tokens", "description": "Refresh the OAuth2 provider access token using a valid refresh token. Returns a new provider session with updated access token, refresh token (if rotated by provider), and expiration information. This endpoint allows maintaining long-lived access to provider APIs without requiring the user to re-authenticate.", "operationId": "refreshProviderToken", "tags": [ "authentication" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SignInProvider" } ], "requestBody": { "description": "Provider refresh token to exchange for a new access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshProviderTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Successfully refreshed provider tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSession" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/token/verify": { "post": { "summary": "Verify JWT token", "description": "Verify the validity of a JWT access token. If no request body is provided, the Authorization header will be used for verification.", "operationId": "verifyToken", "tags": [ "session" ], "security": [ { "BearerAuth": [] }, {} ], "requestBody": { "description": "Optional JWT token to verify (if not provided, Authorization header will be used)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyTokenRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "type": "string", "example": "OK" } } }, "description": "Valid JWT token" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/user": { "get": { "summary": "Get user information", "description": "Retrieve the authenticated user's profile information including roles, metadata, and account status.", "operationId": "getUser", "tags": [ "user" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } }, "description": "User information" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/user/deanonymize": { "post": { "summary": "Deanonymize an anonymous user", "description": "Convert an anonymous user to a regular user by adding email and optionally password credentials. A confirmation email will be sent if the server is configured to do so.", "operationId": "deanonymizeUser", "tags": [ "authentication" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "Authentication method and credentials to convert anonymous user to regular user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDeanonymizeRequest" } } }, "required": true }, "responses": { "200": { "description": "User deanonymized successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/user/deanonymize/sms": { "post": { "summary": "Deanonymize an anonymous user with SMS OTP", "description": "Convert an anonymous user to a regular user by adding a phone number. A one-time password is sent to the\nphone number; the user completes verification by calling `/signin/passwordless/sms/otp` with the OTP, which\nmarks the phone number as verified and returns a session.\n", "operationId": "deanonymizeUserSms", "tags": [ "authentication" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "Phone number and optional user options used to stage deanonymization pending OTP verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDeanonymizeSmsRequest" } } }, "required": true }, "responses": { "200": { "description": "OTP sent to the phone number and the deanonymization change is pending verification. The user remains anonymous until the OTP is verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/user/email/change": { "post": { "summary": "Change user email", "description": "Request to change the authenticated user's email address. A verification email will be sent to the new address to confirm the change. Requires elevated permissions.", "operationId": "changeUserEmail", "tags": [ "user" ], "security": [ { "BearerAuthElevated": [] } ], "requestBody": { "description": "New email address and optional redirect URL for email change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserEmailChangeRequest" } } }, "required": true }, "responses": { "200": { "description": "Email change requested. An email with a verification link has been sent to the new address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/user/phone-number/change": { "post": { "summary": "Change user phone number", "description": "Request to change the authenticated user's phone number. A one-time password is sent\nvia SMS to the new phone number; complete the change by calling\n`/user/phone-number/change/verify` with the OTP. The current `phone_number` is left\nunchanged until verification succeeds. Requires elevated permissions.\n", "operationId": "changeUserPhoneNumber", "tags": [ "user" ], "security": [ { "BearerAuthElevated": [] } ], "requestBody": { "description": "New phone number to verify and bind to the user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPhoneNumberChangeRequest" } } }, "required": true }, "responses": { "200": { "description": "Phone number change requested. An SMS with a verification code has been sent to the new phone number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/user/phone-number/change/verify": { "post": { "summary": "Verify phone number change", "description": "Complete a previously-requested phone number change by submitting the OTP that was\nsent via SMS. On success the staged phone number becomes the user's verified phone\nnumber. Requires elevated permissions.\n", "operationId": "verifyChangeUserPhoneNumber", "tags": [ "user" ], "security": [ { "BearerAuthElevated": [] } ], "requestBody": { "description": "New phone number and OTP code to confirm the change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPhoneNumberChangeVerifyRequest" } } }, "required": true }, "responses": { "200": { "description": "Phone number change verified successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/user/email/send-verification-email": { "post": { "summary": "Send verification email", "description": "Send an email verification link to the specified email address. Used to verify email addresses for new accounts or email changes.", "operationId": "sendVerificationEmail", "tags": [ "user" ], "requestBody": { "description": "Email address and optional redirect URL for verification email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserEmailSendVerificationEmailRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } }, "description": "Email verification email sent successfully" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/user/mfa": { "post": { "summary": "Manage multi-factor authentication", "description": "Activate or deactivate multi-factor authentication for the authenticated user", "operationId": "verifyChangeUserMfa", "tags": [ "security" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "TOTP verification code and MFA activation settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserMfaRequest" } } }, "required": true }, "responses": { "200": { "description": "MFA status successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/user/password": { "post": { "summary": "Change user password", "description": "Change the user's password. The user must be authenticated with elevated permissions or provide a valid password reset ticket.\n\nAll of the user's existing sessions are revoked atomically as part of this operation, including the session used to make the request. Clients must treat the user as signed out after a successful response and obtain a new session via sign-in.\n", "operationId": "changeUserPassword", "tags": [ "user" ], "security": [ { "BearerAuthElevated": [] }, {} ], "requestBody": { "description": "New password and optional password reset ticket for authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPasswordRequest" } } }, "required": true }, "responses": { "200": { "description": "Password changed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/user/password/reset": { "post": { "summary": "Request password reset", "description": "Request a password reset for a user account. An email with a verification link will be sent to the user's email address to complete the password reset process.", "operationId": "sendPasswordResetEmail", "tags": [ "user" ], "requestBody": { "description": "Email address and optional redirect URL for password reset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPasswordResetRequest" } } }, "required": true }, "responses": { "200": { "description": "Password reset requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OKResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/user/webauthn/add": { "post": { "summary": "Initialize adding of a new webauthn security key", "description": "Start the process of adding a new WebAuthn security key to the user's account. Returns a challenge that must be completed by the user's authenticator device. Requires elevated permissions.", "operationId": "addSecurityKey", "tags": [ "security" ], "security": [ { "BearerAuthElevated": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKeyCredentialCreationOptions" } } }, "description": "Challenge created for registering a new security key" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/user/webauthn/verify": { "post": { "summary": "Verify adding of a new webauthn security key", "description": "Complete the process of adding a new WebAuthn security key by verifying the authenticator response. Requires elevated permissions.", "operationId": "verifyAddSecurityKey", "tags": [ "security" ], "security": [ { "BearerAuthElevated": [] } ], "requestBody": { "description": "WebAuthn credential creation response and optional security key nickname", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyAddSecurityKeyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyAddSecurityKeyResponse" } } }, "description": "Security key successfully added" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/token/exchange": { "post": { "summary": "Exchange authorization code for session", "description": "Exchange an authorization code (obtained via PKCE flow) together with the original code_verifier for a session containing access and refresh tokens.", "operationId": "tokenExchange", "tags": [ "session" ], "requestBody": { "description": "Authorization code and code verifier for PKCE exchange", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenExchangeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionPayload" } } }, "description": "Session successfully created" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/verify": { "get": { "summary": "Verify email and authentication tickets", "description": "Verify tickets created by email verification, magic link authentication, or password reset processes. Redirects the user to the appropriate destination upon successful verification.", "operationId": "verifyTicket", "tags": [ "verification" ], "parameters": [ { "$ref": "#/components/parameters/TicketQuery" }, { "$ref": "#/components/parameters/TicketTypeQuery" }, { "$ref": "#/components/parameters/RedirectToQuery" }, { "name": "codeChallenge", "in": "query", "required": false, "description": "PKCE code challenge (S256). When present, the redirect will contain an authorization code instead of a refresh token.", "schema": { "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "responses": { "302": { "description": "Redirect response", "headers": { "Location": { "$ref": "#/components/headers/RedirectLocation" } }, "content": {} }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/version": { "get": { "summary": "Get service version", "description": "Retrieve version information about the authentication service", "operationId": "getVersion", "tags": [ "system" ], "responses": { "200": { "description": "Version information successfully retrieved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "string", "description": "The version of the authentication service", "example": "1.2.3" } }, "required": [ "version" ] } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred while processing the request" } } } }, "/.well-known/openid-configuration": { "get": { "summary": "OpenID Connect Discovery", "description": "Returns the OpenID Provider Metadata (RFC 8414)", "operationId": "getOpenIDConfiguration", "tags": [ "system" ], "responses": { "200": { "description": "OpenID Provider Metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2DiscoveryResponse" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ErrorResponse" } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "summary": "OAuth2 Authorization Server Metadata", "description": "Returns the Authorization Server Metadata (RFC 8414). Same content as OpenID Discovery.", "operationId": "getOAuthAuthorizationServer", "tags": [ "system" ], "responses": { "200": { "description": "Authorization Server Metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2DiscoveryResponse" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ErrorResponse" } } } } } } }, "/oauth2/authorize": { "get": { "summary": "OAuth2 Authorization Endpoint", "description": "Initiates an OAuth2 authorization code flow. Validates the request and redirects to the login UI for user authentication and consent.", "operationId": "oauth2Authorize", "tags": [ "authentication" ], "parameters": [ { "name": "client_id", "in": "query", "required": true, "description": "The OAuth2 client identifier (RFC 6749 Section 2.2).", "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "description": "The URI to redirect the user-agent to after authorization (RFC 6749 Section 3.1.2).", "schema": { "type": "string" } }, { "name": "response_type", "in": "query", "required": true, "description": "The authorization response type. Only 'code' is supported (RFC 6749 Section 3.1.1).", "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "description": "Space-delimited list of requested scopes (RFC 6749 Section 3.3).", "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "description": "Opaque value used to maintain state between the request and callback (RFC 6749 Section 4.1.1).", "schema": { "type": "string" } }, { "name": "nonce", "in": "query", "required": false, "description": "String value used to associate a client session with an ID token (OpenID Connect Core Section 3.1.2.1).", "schema": { "type": "string" } }, { "name": "code_challenge", "in": "query", "required": false, "description": "PKCE code challenge derived from the code verifier (RFC 7636 Section 4.2).", "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "required": false, "description": "Only S256 is supported. The plain method is not allowed.", "schema": { "type": "string", "enum": [ "S256" ] } }, { "name": "resource", "in": "query", "required": false, "description": "Resource indicator for the target service (RFC 8707).", "schema": { "type": "string" } }, { "name": "prompt", "in": "query", "required": false, "description": "Space-delimited list of prompts to present to the user (OpenID Connect Core Section 3.1.2.1).", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to login UI or back to client with error", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ErrorResponse" } } }, "description": "OAuth2 error response" } } }, "post": { "summary": "OAuth2 Authorization Endpoint (POST)", "description": "Initiates an OAuth2 authorization code flow via POST. Validates the request and redirects to the login UI for user authentication and consent.", "operationId": "oauth2AuthorizePost", "tags": [ "authentication" ], "requestBody": { "description": "OAuth2 authorization request parameters (RFC 6749 Section 4.1.1).", "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "redirect_uri": { "type": "string" }, "response_type": { "type": "string" }, "scope": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "nonce": { "type": "string", "nullable": true }, "code_challenge": { "type": "string", "nullable": true }, "code_challenge_method": { "description": "Only S256 is supported. The plain method is not allowed.", "type": "string", "nullable": true }, "resource": { "type": "string", "nullable": true }, "prompt": { "type": "string", "nullable": true } }, "required": [ "client_id", "redirect_uri", "response_type" ] } } } }, "responses": { "302": { "description": "Redirect to login UI or back to client with error", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ErrorResponse" } } }, "description": "OAuth2 error response" } } } }, "/oauth2/token": { "post": { "summary": "OAuth2 Token Endpoint", "description": "Exchange an authorization code for tokens, or refresh an existing token. Supports grant_type authorization_code and refresh_token.", "operationId": "oauth2Token", "tags": [ "authentication" ], "requestBody": { "description": "Token request parameters (RFC 6749 Section 4.1.3).", "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuth2TokenRequest" } } } }, "responses": { "200": { "description": "Token response", "headers": { "Cache-Control": { "schema": { "type": "string" }, "required": true }, "Pragma": { "schema": { "type": "string" }, "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2TokenResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ErrorResponse" } } }, "description": "OAuth2 error response" } } } }, "/oauth2/userinfo": { "get": { "summary": "OpenID Connect UserInfo Endpoint (GET)", "description": "Returns claims about the authenticated user based on the access token scopes.", "operationId": "oauth2UserinfoGet", "tags": [ "user" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "UserInfo claims", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2UserinfoResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ErrorResponse" } } }, "description": "OAuth2 error response" } } }, "post": { "summary": "OpenID Connect UserInfo Endpoint (POST)", "description": "Returns claims about the authenticated user based on the access token scopes.", "operationId": "oauth2UserinfoPost", "tags": [ "user" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "UserInfo claims", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2UserinfoResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ErrorResponse" } } }, "description": "OAuth2 error response" } } } }, "/oauth2/jwks": { "get": { "summary": "OAuth2 Provider JWKS Endpoint", "description": "Returns the JSON Web Key Set containing public keys used for OAuth2/OIDC token signing.", "operationId": "oauth2Jwks", "tags": [ "system" ], "responses": { "200": { "description": "JWKS response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2JWKSResponse" } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ErrorResponse" } } } } } } }, "/oauth2/revoke": { "post": { "summary": "OAuth2 Token Revocation (RFC 7009)", "description": "Revoke an access token or refresh token.", "operationId": "oauth2Revoke", "tags": [ "session" ], "requestBody": { "description": "Token revocation request parameters (RFC 7009 Section 2.1).", "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuth2RevokeRequest" } } } }, "responses": { "200": { "description": "Token successfully revoked (or was already invalid)" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ErrorResponse" } } }, "description": "OAuth2 error response" } } } }, "/oauth2/introspect": { "post": { "summary": "OAuth2 Token Introspection (RFC 7662)", "description": "Introspect a token to determine its current state and metadata.", "operationId": "oauth2Introspect", "tags": [ "session" ], "requestBody": { "description": "Token introspection request parameters (RFC 7662 Section 2.1).", "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OAuth2IntrospectRequest" } } } }, "responses": { "200": { "description": "Token introspection response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2IntrospectResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ErrorResponse" } } }, "description": "OAuth2 error response" } } } }, "/oauth2/login": { "get": { "summary": "Get authorization request details for consent screen", "description": "Called by the consent UI to get details about the pending authorization request.", "operationId": "oauth2LoginGet", "tags": [ "authentication" ], "parameters": [ { "name": "request_id", "in": "query", "required": true, "description": "The pending authorization request identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Authorization request details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2LoginResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred" } } }, "post": { "summary": "Complete login/consent for an authorization request", "description": "Called by the consent UI after user authenticates and consents. Sets the user on the auth request and redirects back to the client with an authorization code.", "operationId": "oauth2LoginPost", "tags": [ "authentication" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "description": "Login consent completion with the authorization request ID.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2LoginRequest" } } } }, "responses": { "200": { "description": "Authorization completed, redirect URL returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2LoginCompleteResponse" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "An error occurred" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer authentication with JWT access token. Used to authenticate requests to protected endpoints." }, "BearerAuthElevated": { "type": "http", "scheme": "bearer", "description": "Bearer authentication that requires elevated permissions. Used for sensitive operations that may require additional security measures such as recent authentication. For details see https://docs.nhost.io/products/auth/elevated-permissions" } }, "schemas": { "AttestationFormat": { "type": "string", "enum": [ "packed", "tpm", "android-key", "android-safetynet", "fido-u2f", "apple", "none" ], "description": "The attestation statement format" }, "AuthenticationExtensions": { "type": "object", "additionalProperties": true, "description": "Additional parameters requesting additional processing by the client and authenticator" }, "AuthenticationExtensionsClientOutputs": { "type": "object", "additionalProperties": true, "description": "Map of extension outputs from the client", "properties": { "appid": { "type": "boolean", "description": "Application identifier extension output" }, "credProps": { "$ref": "#/components/schemas/CredentialPropertiesOutput" }, "hmacCreateSecret": { "type": "boolean", "description": "HMAC secret extension output" } } }, "AuthenticatorAssertionResponse": { "type": "object", "additionalProperties": false, "properties": { "clientDataJSON": { "type": "string", "description": "Base64url encoded client data JSON" }, "authenticatorData": { "type": "string", "description": "Base64url encoded authenticator data" }, "signature": { "type": "string", "description": "Base64url encoded assertion signature" }, "userHandle": { "type": "string", "nullable": true, "description": "Base64url encoded user handle" } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ] }, "AuthenticatorAttachment": { "type": "string", "enum": [ "platform", "cross-platform" ], "description": "The authenticator attachment modality" }, "AuthenticatorAttestationResponse": { "type": "object", "additionalProperties": false, "properties": { "clientDataJSON": { "$ref": "#/components/schemas/URLEncodedBase64" }, "transports": { "type": "array", "items": { "type": "string" }, "description": "The authenticator transports" }, "authenticatorData": { "$ref": "#/components/schemas/URLEncodedBase64" }, "publicKey": { "$ref": "#/components/schemas/URLEncodedBase64" }, "publicKeyAlgorithm": { "type": "integer", "format": "int64", "description": "The public key algorithm identifier" }, "attestationObject": { "$ref": "#/components/schemas/URLEncodedBase64" } }, "required": [ "clientDataJSON", "attestationObject" ] }, "AuthenticatorSelection": { "type": "object", "additionalProperties": false, "properties": { "authenticatorAttachment": { "$ref": "#/components/schemas/AuthenticatorAttachment" }, "requireResidentKey": { "type": "boolean", "description": "Whether the authenticator must create a client-side-resident public key credential source" }, "residentKey": { "$ref": "#/components/schemas/ResidentKeyRequirement" }, "userVerification": { "$ref": "#/components/schemas/UserVerificationRequirement" } } }, "AuthenticatorTransport": { "type": "string", "enum": [ "usb", "nfc", "ble", "smart-card", "hybrid", "internal" ], "description": "The authenticator transports that can be used" }, "ConveyancePreference": { "type": "string", "enum": [ "none", "indirect", "direct", "enterprise" ], "default": "none", "description": "The attestation conveyance preference" }, "CreatePATRequest": { "type": "object", "additionalProperties": false, "properties": { "expiresAt": { "description": "Expiration date of the PAT", "format": "date-time", "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "example": { "name": "my-pat", "used-by": "my-app-cli" }, "properties": {} } }, "required": [ "expiresAt" ] }, "CreatePATResponse": { "type": "object", "additionalProperties": false, "properties": { "id": { "description": "ID of the PAT", "example": "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24", "pattern": "\\b[0-9a-f]{8}\\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\\b[0-9a-f]{12}\\b", "type": "string" }, "personalAccessToken": { "description": "PAT", "example": "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24", "pattern": "\\b[0-9a-f]{8}\\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\\b[0-9a-f]{12}\\b", "type": "string" } }, "required": [ "id", "personalAccessToken" ] }, "CredentialAssertionResponse": { "type": "object", "x-go-type-import": { "name": "protocol", "path": "github.com/go-webauthn/webauthn/protocol" }, "x-go-type": "protocol.CredentialAssertionResponse", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The credential's identifier" }, "type": { "type": "string", "description": "The credential type represented by this object" }, "rawId": { "$ref": "#/components/schemas/URLEncodedBase64" }, "clientExtensionResults": { "$ref": "#/components/schemas/AuthenticationExtensionsClientOutputs" }, "authenticatorAttachment": { "type": "string", "description": "The authenticator attachment" }, "response": { "$ref": "#/components/schemas/AuthenticatorAssertionResponse" } }, "required": [ "id", "type", "rawId", "response" ] }, "CredentialCreationResponse": { "type": "object", "additionalProperties": false, "x-go-type-import": { "name": "protocol", "path": "github.com/go-webauthn/webauthn/protocol" }, "x-go-type": "protocol.CredentialCreationResponse", "properties": { "id": { "type": "string", "description": "The credential's identifier" }, "type": { "type": "string", "description": "The credential type represented by this object" }, "rawId": { "$ref": "#/components/schemas/URLEncodedBase64" }, "clientExtensionResults": { "$ref": "#/components/schemas/AuthenticationExtensionsClientOutputs" }, "authenticatorAttachment": { "type": "string", "description": "The authenticator attachment" }, "response": { "$ref": "#/components/schemas/AuthenticatorAttestationResponse" } }, "required": [ "id", "type", "rawId", "response" ] }, "CredentialParameter": { "type": "object", "additionalProperties": false, "properties": { "type": { "$ref": "#/components/schemas/CredentialType" }, "alg": { "type": "integer", "description": "The cryptographic algorithm identifier" } }, "required": [ "type", "alg" ] }, "CredentialPropertiesOutput": { "type": "object", "additionalProperties": false, "description": "Credential properties extension output", "properties": { "rk": { "type": "boolean", "description": "Indicates if the credential is a resident key" } } }, "CredentialType": { "type": "string", "enum": [ "public-key" ], "description": "The valid credential types" }, "ErrorResponse": { "type": "object", "description": "Standardized error response", "additionalProperties": false, "properties": { "status": { "description": "HTTP status error code", "type": "integer", "example": 400 }, "message": { "description": "Human-friendly error message", "type": "string", "example": "Invalid email format" }, "error": { "description": "Error code identifying the specific application error", "type": "string", "enum": [ "default-role-must-be-in-allowed-roles", "disabled-endpoint", "disabled-user", "user-already-exists", "email-already-verified", "forbidden-anonymous", "internal-server-error", "invalid-email-password", "invalid-request", "locale-not-allowed", "password-too-short", "password-in-hibp-database", "redirectTo-not-allowed", "role-not-allowed", "signup-disabled", "unverified-user", "user-not-anonymous", "invalid-pat", "invalid-refresh-token", "invalid-ticket", "disabled-mfa-totp", "no-totp-secret", "invalid-totp", "mfa-type-not-found", "totp-already-active", "invalid-state", "oauth-token-echange-failed", "oauth-profile-fetch-failed", "oauth-provider-error", "invalid-otp", "otp-too-many-attempts", "cannot-send-sms", "provider-account-already-linked" ] } }, "required": [ "status", "message", "error" ] }, "IdTokenProvider": { "type": "string", "additionalProperties": false, "enum": [ "apple", "google" ] }, "JWK": { "type": "object", "description": "JSON Web Key for JWT verification", "additionalProperties": false, "properties": { "alg": { "type": "string", "description": "Algorithm used with this key", "example": "RS256" }, "e": { "type": "string", "description": "RSA public exponent", "example": "AQAB" }, "kid": { "type": "string", "description": "Key ID", "example": "key-id-1" }, "kty": { "type": "string", "description": "Key type", "example": "RSA" }, "n": { "type": "string", "description": "RSA modulus", "example": "abcd1234..." }, "use": { "type": "string", "description": "Key usage", "example": "sig" } }, "required": [ "alg", "e", "kid", "kty", "n", "use" ] }, "JWKSet": { "type": "object", "description": "JSON Web Key Set for verifying JWT signatures", "additionalProperties": false, "properties": { "keys": { "type": "array", "description": "Array of public keys", "items": { "$ref": "#/components/schemas/JWK" } } }, "required": [ "keys" ] }, "LinkIdTokenRequest": { "type": "object", "additionalProperties": false, "properties": { "provider": { "$ref": "#/components/schemas/IdTokenProvider" }, "idToken": { "type": "string", "description": "Apple ID token" }, "nonce": { "type": "string", "description": "Nonce used during sign in process" } }, "required": [ "provider", "idToken" ] }, "MFAChallengePayload": { "type": "object", "description": "Challenge payload for multi-factor authentication", "additionalProperties": false, "properties": { "ticket": { "type": "string", "description": "Ticket to use when completing the MFA challenge", "example": "mfaTotp:abc123def456" } }, "required": [ "ticket" ] }, "OKResponse": { "type": "string", "additionalProperties": false, "enum": [ "OK" ] }, "OptionsRedirectTo": { "type": "object", "additionalProperties": false, "properties": { "redirectTo": { "type": "string", "format": "uri", "example": "https://my-app.com/catch-redirection" } } }, "PublicKeyCredentialCreationOptions": { "type": "object", "x-go-type-import": { "name": "protocol", "path": "github.com/go-webauthn/webauthn/protocol" }, "x-go-type": "protocol.PublicKeyCredentialCreationOptions", "additionalProperties": false, "properties": { "rp": { "$ref": "#/components/schemas/RelyingPartyEntity" }, "user": { "$ref": "#/components/schemas/UserEntity" }, "challenge": { "$ref": "#/components/schemas/URLEncodedBase64" }, "pubKeyCredParams": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialParameter" }, "description": "The desired credential types and their respective cryptographic parameters" }, "timeout": { "type": "integer", "description": "A time, in milliseconds, that the caller is willing to wait for the call to complete" }, "excludeCredentials": { "type": "array", "items": { "$ref": "#/components/schemas/PublicKeyCredentialDescriptor" }, "description": "A list of PublicKeyCredentialDescriptor objects representing public key credentials that are not acceptable to the caller" }, "authenticatorSelection": { "$ref": "#/components/schemas/AuthenticatorSelection" }, "hints": { "type": "array", "items": { "$ref": "#/components/schemas/PublicKeyCredentialHints" }, "description": "Hints to help guide the user through the experience" }, "attestation": { "$ref": "#/components/schemas/ConveyancePreference" }, "attestationFormats": { "type": "array", "items": { "$ref": "#/components/schemas/AttestationFormat" }, "description": "The preferred attestation statement formats" }, "extensions": { "$ref": "#/components/schemas/AuthenticationExtensions" } }, "required": [ "rp", "user", "challenge", "pubKeyCredParams" ] }, "PublicKeyCredentialDescriptor": { "type": "object", "additionalProperties": false, "properties": { "type": { "$ref": "#/components/schemas/CredentialType" }, "id": { "$ref": "#/components/schemas/URLEncodedBase64" }, "transports": { "type": "array", "items": { "$ref": "#/components/schemas/AuthenticatorTransport" }, "description": "The authenticator transports that can be used" } }, "required": [ "type", "id" ] }, "PublicKeyCredentialHints": { "type": "string", "enum": [ "security-key", "client-device", "hybrid" ], "description": "Hints to help guide the user through the experience" }, "PublicKeyCredentialRequestOptions": { "type": "object", "x-go-type-import": { "name": "protocol", "path": "github.com/go-webauthn/webauthn/protocol" }, "x-go-type": "protocol.PublicKeyCredentialRequestOptions", "additionalProperties": false, "properties": { "challenge": { "$ref": "#/components/schemas/URLEncodedBase64" }, "timeout": { "type": "integer", "description": "A time, in milliseconds, that the caller is willing to wait for the call to complete" }, "rpId": { "type": "string", "description": "The RP ID the credential should be scoped to" }, "allowCredentials": { "type": "array", "items": { "$ref": "#/components/schemas/PublicKeyCredentialDescriptor" }, "description": "A list of CredentialDescriptor objects representing public key credentials acceptable to the caller" }, "userVerification": { "$ref": "#/components/schemas/UserVerificationRequirement" }, "hints": { "type": "array", "items": { "$ref": "#/components/schemas/PublicKeyCredentialHints" }, "description": "Hints to help guide the user through the experience" }, "extensions": { "$ref": "#/components/schemas/AuthenticationExtensions" } }, "required": [ "challenge" ] }, "ProviderSession": { "type": "object", "description": "OAuth2 provider session containing access and refresh tokens", "additionalProperties": false, "properties": { "accessToken": { "type": "string", "description": "OAuth2 provider access token for API calls", "example": "ya29.a0AfH6SMBx..." }, "expiresIn": { "type": "integer", "description": "Number of seconds until the access token expires", "example": 3599 }, "expiresAt": { "type": "string", "format": "date-time", "description": "Timestamp when the access token expires", "example": "2024-12-31T23:59:59Z" }, "refreshToken": { "type": "string", "nullable": true, "description": "OAuth2 provider refresh token for obtaining new access tokens (if provided by the provider)", "example": "1//0gK8..." } }, "required": [ "accessToken", "expiresIn", "expiresAt" ] }, "ProviderSpecificParams": { "type": "object", "properties": { "connection": { "type": "string", "description": "(workos) Specifies the connection to use for authentication" }, "organization": { "type": "string", "description": "(workos) Specifies the organization to use for authentication" } } }, "UpstreamAuthParams": { "type": "object", "description": "Extra parameters forwarded to the upstream OAuth2 provider's authorization URL (e.g. Google's prompt or login_hint). Reserved OAuth2/OIDC parameters are rejected.\n", "additionalProperties": { "type": "string" } }, "RefreshProviderTokenRequest": { "type": "object", "description": "Request to refresh OAuth2 provider tokens", "additionalProperties": false, "properties": { "refreshToken": { "type": "string", "description": "OAuth2 provider refresh token obtained from previous authentication", "example": "1//0gK8..." } }, "required": [ "refreshToken" ] }, "RefreshTokenRequest": { "type": "object", "description": "Request to refresh an access token", "additionalProperties": false, "properties": { "refreshToken": { "description": "Refresh token used to generate a new access token", "example": "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24", "pattern": "\\b[0-9a-f]{8}\\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\\b[0-9a-f]{12}\\b", "type": "string" } }, "required": [ "refreshToken" ] }, "RelyingPartyEntity": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "A human-palatable name for the entity" }, "id": { "type": "string", "description": "A unique identifier for the Relying Party entity, which sets the RP ID" } }, "required": [ "name", "id" ] }, "ResidentKeyRequirement": { "type": "string", "enum": [ "discouraged", "preferred", "required" ], "default": "discouraged", "description": "The resident key requirement" }, "Session": { "type": "object", "description": "User authentication session containing tokens and user information", "additionalProperties": false, "properties": { "accessToken": { "type": "string", "description": "JWT token for authenticating API requests", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "accessTokenExpiresIn": { "type": "integer", "format": "int64", "description": "Expiration time of the access token in seconds", "example": 900 }, "refreshTokenId": { "description": "Identifier for the refresh token", "example": "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24", "pattern": "\\b[0-9a-f]{8}\\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\\b[0-9a-f]{12}\\b", "type": "string" }, "refreshToken": { "description": "Token used to refresh the access token", "example": "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24", "pattern": "\\b[0-9a-f]{8}\\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\\b[0-9a-f]{12}\\b", "type": "string" }, "user": { "$ref": "#/components/schemas/User" } }, "required": [ "accessToken", "accessTokenExpiresIn", "refreshToken", "refreshTokenId" ] }, "SessionPayload": { "type": "object", "description": "Container for session information", "additionalProperties": false, "properties": { "session": { "$ref": "#/components/schemas/Session" } } }, "SignInAnonymousRequest": { "type": "object", "additionalProperties": false, "properties": { "displayName": { "example": "John Smith", "type": "string" }, "locale": { "description": "A two or three characters locale", "example": "en", "maxLength": 3, "minLength": 2, "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "example": { "firstName": "John", "lastName": "Smith" }, "properties": {} } } }, "SignInEmailPasswordRequest": { "type": "object", "description": "Request to authenticate using email and password", "additionalProperties": false, "properties": { "email": { "description": "User's email address", "example": "john.smith@nhost.io", "format": "email", "type": "string" }, "password": { "description": "User's password", "example": "Str0ngPassw#ord-94|%", "minLength": 3, "maxLength": 50, "type": "string" } }, "required": [ "email", "password" ] }, "SignInEmailPasswordResponse": { "type": "object", "description": "Response for email-password authentication that may include a session or MFA challenge", "additionalProperties": false, "properties": { "session": { "$ref": "#/components/schemas/Session" }, "mfa": { "$ref": "#/components/schemas/MFAChallengePayload" } } }, "SignInIdTokenRequest": { "type": "object", "additionalProperties": false, "properties": { "provider": { "$ref": "#/components/schemas/IdTokenProvider" }, "idToken": { "type": "string", "description": "Apple ID token" }, "nonce": { "type": "string", "description": "Nonce used during sign in process" }, "options": { "$ref": "#/components/schemas/SignUpOptions" } }, "required": [ "provider", "idToken" ] }, "ElevationMethod": { "type": "string", "description": "Method that can be used to elevate a session", "enum": [ "webauthn", "totp", "otp-email", "otp-sms" ], "example": "totp" }, "ElevationMethodsResponse": { "type": "object", "additionalProperties": false, "description": "Elevation status of the user", "properties": { "elevationRequired": { "type": "boolean", "description": "Whether protected endpoints require an elevated session. When true and no methods are available, the user must set up a second factor first", "example": true }, "methods": { "type": "array", "description": "Methods the user can use to elevate their session", "example": [ "webauthn", "totp" ], "items": { "$ref": "#/components/schemas/ElevationMethod" } }, "sessionElevated": { "type": "boolean", "description": "Whether the bearer token has an elevated claim matching its subject", "example": false } }, "required": [ "elevationRequired", "methods", "sessionElevated" ] }, "ElevateTotpRequest": { "type": "object", "additionalProperties": false, "properties": { "otp": { "type": "string", "description": "One time password" } }, "required": [ "otp" ] }, "ElevateOTPEmailVerifyRequest": { "type": "object", "additionalProperties": false, "properties": { "otp": { "type": "string", "description": "One time password" } }, "required": [ "otp" ] }, "ElevateOTPSmsVerifyRequest": { "type": "object", "additionalProperties": false, "properties": { "otp": { "type": "string", "description": "One time password" } }, "required": [ "otp" ] }, "SignInMfaTotpRequest": { "type": "object", "additionalProperties": false, "properties": { "ticket": { "type": "string", "description": "Ticket", "pattern": "^mfaTotp:.*$" }, "otp": { "type": "string", "description": "One time password" } }, "required": [ "ticket", "otp" ] }, "SignInOTPEmailRequest": { "type": "object", "additionalProperties": false, "properties": { "email": { "description": "A valid email", "example": "john.smith@nhost.io", "format": "email", "type": "string" }, "options": { "$ref": "#/components/schemas/SignUpOptions" } }, "required": [ "email" ] }, "SignInOTPEmailVerifyRequest": { "type": "object", "additionalProperties": false, "properties": { "otp": { "type": "string", "description": "One time password" }, "email": { "description": "A valid email", "example": "john.smith@nhost.io", "format": "email", "type": "string" } }, "required": [ "otp", "email" ] }, "SignInOTPEmailVerifyResponse": { "type": "object", "additionalProperties": false, "properties": { "session": { "$ref": "#/components/schemas/Session" } } }, "SignInPATRequest": { "type": "object", "additionalProperties": false, "properties": { "personalAccessToken": { "description": "PAT", "example": "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24", "pattern": "\\b[0-9a-f]{8}\\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\\b[0-9a-f]{12}\\b", "type": "string" } }, "required": [ "personalAccessToken" ] }, "SignInPasswordlessEmailRequest": { "type": "object", "additionalProperties": false, "properties": { "email": { "description": "A valid email", "example": "john.smith@nhost.io", "format": "email", "type": "string" }, "options": { "$ref": "#/components/schemas/SignUpOptions" }, "codeChallenge": { "description": "PKCE code challenge (S256). When provided, the verification redirect will contain an authorization code instead of a refresh token.", "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "email" ] }, "SignInPasswordlessSmsOtpRequest": { "type": "object", "additionalProperties": false, "properties": { "phoneNumber": { "description": "Phone number of the user", "example": "+123456789", "type": "string" }, "otp": { "type": "string", "description": "One-time password received by SMS" } }, "required": [ "phoneNumber", "otp" ] }, "SignInPasswordlessSmsOtpResponse": { "type": "object", "additionalProperties": false, "properties": { "session": { "$ref": "#/components/schemas/Session" }, "mfa": { "$ref": "#/components/schemas/MFAChallengePayload" } } }, "SignInPasswordlessSmsRequest": { "type": "object", "additionalProperties": false, "properties": { "phoneNumber": { "description": "Phone number of the user", "example": "+123456789", "type": "string" }, "options": { "$ref": "#/components/schemas/SignUpOptions" } }, "required": [ "phoneNumber" ] }, "SignUpPasswordlessEmailRequest": { "type": "object", "additionalProperties": false, "properties": { "email": { "description": "A valid email", "example": "john.smith@nhost.io", "format": "email", "type": "string" }, "options": { "$ref": "#/components/schemas/SignUpOptions" }, "codeChallenge": { "description": "PKCE code challenge (S256). When provided, the verification redirect will contain an authorization code instead of a refresh token.", "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "email" ] }, "SignUpOTPEmailRequest": { "type": "object", "additionalProperties": false, "properties": { "email": { "description": "A valid email", "example": "john.smith@nhost.io", "format": "email", "type": "string" }, "options": { "$ref": "#/components/schemas/SignUpOptions" } }, "required": [ "email" ] }, "SignUpPasswordlessSmsRequest": { "type": "object", "additionalProperties": false, "properties": { "phoneNumber": { "description": "Phone number of the user", "example": "+123456789", "type": "string" }, "options": { "$ref": "#/components/schemas/SignUpOptions" } }, "required": [ "phoneNumber" ] }, "SignUpIdTokenRequest": { "type": "object", "additionalProperties": false, "properties": { "provider": { "$ref": "#/components/schemas/IdTokenProvider" }, "idToken": { "type": "string", "description": "Apple or Google ID token" }, "nonce": { "type": "string", "description": "Nonce used during sign in process" }, "options": { "$ref": "#/components/schemas/SignUpOptions" } }, "required": [ "provider", "idToken" ] }, "SignInWebauthnRequest": { "type": "object", "additionalProperties": false, "properties": { "email": { "description": "A valid email", "example": "john.smith@nhost.io", "format": "email", "type": "string" } } }, "SignInWebauthnVerifyRequest": { "type": "object", "additionalProperties": false, "properties": { "email": { "description": "A valid email. Deprecated, no longer used", "example": "john.smith@nhost.io", "format": "email", "type": "string", "deprecated": true }, "credential": { "$ref": "#/components/schemas/CredentialAssertionResponse" } }, "required": [ "credential" ] }, "SignOutRequest": { "type": "object", "properties": { "refreshToken": { "type": "string", "description": "Refresh token for the current session" }, "all": { "type": "boolean", "default": false, "description": "Sign out from all connected devices" } } }, "SignUpEmailPasswordRequest": { "type": "object", "description": "Request to register a new user with email and password", "additionalProperties": false, "properties": { "email": { "description": "Email address for the new user account", "example": "john.smith@nhost.io", "format": "email", "type": "string" }, "password": { "description": "Password for the new user account", "example": "Str0ngPassw#ord-94|%", "minLength": 3, "maxLength": 50, "type": "string" }, "options": { "$ref": "#/components/schemas/SignUpOptions" }, "codeChallenge": { "description": "PKCE code challenge (S256). When provided and email verification is required, the verification redirect will contain an authorization code instead of a refresh token.", "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "email", "password" ] }, "SignUpOptions": { "type": "object", "additionalProperties": false, "properties": { "allowedRoles": { "example": [ "me", "user" ], "type": "array", "items": { "type": "string" } }, "defaultRole": { "example": "user", "type": "string" }, "displayName": { "example": "John Smith", "type": "string", "pattern": "^[\\p{L}\\p{N}\\p{S} ,.'-]+$", "maxLength": 32 }, "locale": { "description": "A two or three characters locale", "example": "en", "maxLength": 3, "minLength": 2, "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "example": { "firstName": "John", "lastName": "Smith" }, "properties": {} }, "redirectTo": { "type": "string", "format": "uri", "example": "https://my-app.com/catch-redirection" } } }, "SignUpWebauthnRequest": { "type": "object", "additionalProperties": false, "properties": { "email": { "description": "A valid email", "example": "john.smith@nhost.io", "format": "email", "type": "string" }, "options": { "$ref": "#/components/schemas/SignUpOptions" } }, "required": [ "email" ] }, "SignUpWebauthnVerifyRequest": { "type": "object", "additionalProperties": false, "properties": { "credential": { "$ref": "#/components/schemas/CredentialCreationResponse" }, "options": { "$ref": "#/components/schemas/SignUpOptions" }, "nickname": { "description": "Nickname for the security key", "type": "string" }, "codeChallenge": { "description": "PKCE code challenge (S256). When provided and email verification is required, the verification redirect will contain an authorization code instead of a refresh token.", "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "credential" ] }, "TokenExchangeRequest": { "type": "object", "description": "Request to exchange an authorization code for a session using PKCE", "additionalProperties": false, "properties": { "code": { "description": "The authorization code received from the redirect", "type": "string" }, "codeVerifier": { "description": "The original PKCE code verifier (43-128 characters)", "type": "string", "minLength": 43, "maxLength": 128 } }, "required": [ "code", "codeVerifier" ] }, "TotpGenerateResponse": { "type": "object", "description": "Response containing TOTP setup information for MFA", "additionalProperties": false, "properties": { "imageUrl": { "type": "string", "description": "URL to QR code image for scanning with an authenticator app", "example": "data:image/png;base64,iVBORw0KGg..." }, "totpSecret": { "type": "string", "description": "TOTP secret key for manual setup with an authenticator app", "example": "ABCDEFGHIJK23456" } }, "required": [ "imageUrl", "totpSecret" ] }, "URLEncodedBase64": { "type": "string", "format": "byte", "description": "Base64url-encoded binary data" }, "User": { "type": "object", "description": "User profile and account information", "additionalProperties": false, "properties": { "avatarUrl": { "type": "string", "description": "URL to the user's profile picture", "example": "https://myapp.com/avatars/user123.jpg" }, "createdAt": { "format": "date-time", "type": "string", "description": "Timestamp when the user account was created", "example": "2023-01-15T12:34:56Z" }, "defaultRole": { "example": "user", "type": "string", "description": "Default authorization role for the user" }, "displayName": { "example": "John Smith", "type": "string", "description": "User's display name" }, "email": { "description": "User's email address", "example": "john.smith@nhost.io", "format": "email", "type": "string" }, "emailVerified": { "type": "boolean", "description": "Whether the user's email has been verified", "example": true }, "id": { "description": "Unique identifier for the user", "example": "2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24", "pattern": "\\b[0-9a-f]{8}\\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\\b[0-9a-f]{12}\\b", "type": "string" }, "isAnonymous": { "type": "boolean", "description": "Whether this is an anonymous user account", "example": false }, "locale": { "description": "User's preferred locale (language code)", "example": "en", "maxLength": 3, "minLength": 2, "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "x-go-type-skip-optional-pointer": true, "description": "Custom metadata associated with the user", "example": { "firstName": "John", "lastName": "Smith" }, "properties": {} }, "phoneNumber": { "type": "string", "description": "User's phone number", "example": "+12025550123" }, "phoneNumberVerified": { "type": "boolean", "description": "Whether the user's phone number has been verified", "example": false }, "roles": { "example": [ "user", "customer" ], "type": "array", "description": "List of roles assigned to the user", "items": { "type": "string" } }, "activeMfaType": { "type": "string", "description": "Active MFA type for the user", "nullable": true } }, "required": [ "avatarUrl", "createdAt", "defaultRole", "displayName", "emailVerified", "id", "isAnonymous", "locale", "metadata", "phoneNumberVerified", "roles" ] }, "UserDeanonymizeRequest": { "type": "object", "additionalProperties": false, "properties": { "signInMethod": { "description": "Which sign-in method to use", "type": "string", "enum": [ "email-password", "passwordless" ] }, "email": { "description": "A valid email", "example": "john.smith@nhost.io", "format": "email", "type": "string" }, "password": { "description": "A password of minimum 3 characters", "example": "Str0ngPassw#ord-94|%", "minLength": 3, "maxLength": 50, "type": "string" }, "connection": { "deprecated": true, "description": "Deprecated, will be ignored", "type": "string" }, "options": { "$ref": "#/components/schemas/SignUpOptions" }, "codeChallenge": { "description": "PKCE code challenge (S256). When provided, the verification redirect will contain an authorization code instead of a refresh token.", "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "signInMethod", "email" ] }, "UserDeanonymizeSmsRequest": { "type": "object", "additionalProperties": false, "properties": { "phoneNumber": { "description": "Phone number of the user", "example": "+123456789", "type": "string" }, "options": { "$ref": "#/components/schemas/SignUpOptions" } }, "required": [ "phoneNumber" ] }, "UserEmailChangeRequest": { "type": "object", "additionalProperties": false, "properties": { "newEmail": { "description": "A valid email", "example": "john.smith@nhost.io", "format": "email", "type": "string" }, "options": { "$ref": "#/components/schemas/OptionsRedirectTo" }, "codeChallenge": { "description": "PKCE code challenge (S256). When provided, the verification redirect will contain an authorization code instead of a refresh token.", "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "newEmail" ] }, "UserPhoneNumberChangeRequest": { "type": "object", "additionalProperties": false, "properties": { "newPhoneNumber": { "description": "New phone number to bind to the user once verified via SMS OTP", "example": "+123456789", "type": "string" } }, "required": [ "newPhoneNumber" ] }, "UserPhoneNumberChangeVerifyRequest": { "type": "object", "additionalProperties": false, "properties": { "newPhoneNumber": { "description": "The phone number that was previously requested via /user/phone-number/change", "example": "+123456789", "type": "string" }, "otp": { "description": "One-time password received via SMS at the new phone number", "example": "123456", "type": "string" } }, "required": [ "newPhoneNumber", "otp" ] }, "UserEmailSendVerificationEmailRequest": { "type": "object", "additionalProperties": false, "properties": { "email": { "description": "A valid email", "example": "john.smith@nhost.io", "format": "email", "type": "string" }, "options": { "$ref": "#/components/schemas/OptionsRedirectTo" }, "codeChallenge": { "description": "PKCE code challenge (S256). When provided, the verification redirect will contain an authorization code instead of a refresh token.", "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "email" ] }, "UserEntity": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "A human-palatable name for the entity" }, "displayName": { "type": "string", "description": "A human-palatable name for the user account, intended only for display" }, "id": { "type": "string", "description": "The user handle of the user account entity" } }, "required": [ "name", "displayName", "id" ] }, "UserMfaRequest": { "type": "object", "description": "Request to activate or deactivate multi-factor authentication", "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Verification code from the authenticator app when activating MFA", "example": "123456" }, "activeMfaType": { "type": "string", "enum": [ "totp", "" ], "description": "Type of MFA to activate. Use empty string to disable MFA.", "example": "totp" } }, "required": [ "code" ] }, "UserPasswordRequest": { "type": "object", "additionalProperties": false, "properties": { "newPassword": { "description": "A password of minimum 3 characters", "example": "Str0ngPassw#ord-94|%", "minLength": 3, "maxLength": 50, "type": "string" }, "ticket": { "type": "string", "pattern": "^passwordReset\\:.*$", "description": "Ticket to reset the password, required if the user is not authenticated" } }, "required": [ "newPassword" ] }, "UserPasswordResetRequest": { "type": "object", "additionalProperties": false, "properties": { "email": { "description": "A valid email", "example": "john.smith@nhost.io", "format": "email", "type": "string" }, "options": { "$ref": "#/components/schemas/OptionsRedirectTo" }, "codeChallenge": { "description": "PKCE code challenge (S256). When provided, the verification redirect will contain an authorization code instead of a refresh token.", "type": "string", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "email" ] }, "UserVerificationRequirement": { "type": "string", "enum": [ "required", "preferred", "discouraged" ], "default": "preferred", "description": "A requirement for user verification for the operation" }, "VerifyAddSecurityKeyRequest": { "type": "object", "additionalProperties": false, "properties": { "credential": { "$ref": "#/components/schemas/CredentialCreationResponse" }, "nickname": { "type": "string", "description": "Optional nickname for the security key" } }, "required": [ "credential" ] }, "VerifyAddSecurityKeyResponse": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "description": "The ID of the newly added security key", "example": "123e4567-e89b-12d3-a456-426614174000" }, "nickname": { "type": "string", "description": "The nickname of the security key if provided" } }, "required": [ "id" ] }, "VerifyTokenRequest": { "type": "object", "additionalProperties": false, "properties": { "token": { "type": "string", "description": "JWT token to verify" } } }, "OAuth2ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "OAuth2 error code" }, "error_description": { "type": "string", "description": "Human-readable error description" } }, "required": [ "error" ] }, "OAuth2DiscoveryResponse": { "type": "object", "properties": { "issuer": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "userinfo_endpoint": { "type": "string" }, "jwks_uri": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "introspection_endpoint": { "type": "string" }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "subject_types_supported": { "type": "array", "items": { "type": "string" } }, "id_token_signing_alg_values_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }, "claims_supported": { "type": "array", "items": { "type": "string" } }, "request_parameter_supported": { "type": "boolean" }, "authorization_response_iss_parameter_supported": { "type": "boolean" }, "client_id_metadata_document_supported": { "type": "boolean" } }, "required": [ "issuer", "authorization_endpoint", "token_endpoint", "jwks_uri", "response_types_supported" ] }, "OAuth2TokenRequest": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "code": { "type": "string", "nullable": true }, "redirect_uri": { "type": "string", "nullable": true }, "client_id": { "type": "string", "nullable": true }, "client_secret": { "type": "string", "nullable": true }, "code_verifier": { "type": "string", "nullable": true }, "refresh_token": { "type": "string", "nullable": true }, "resource": { "type": "string", "nullable": true } }, "required": [ "grant_type" ] }, "OAuth2TokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "id_token": { "type": "string" }, "scope": { "type": "string" } }, "required": [ "access_token", "token_type", "expires_in" ] }, "OAuth2UserinfoResponse": { "type": "object", "additionalProperties": true, "properties": { "sub": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "email_verified": { "type": "boolean" }, "picture": { "type": "string" }, "locale": { "type": "string" }, "phone_number": { "type": "string" }, "phone_number_verified": { "type": "boolean" } }, "required": [ "sub" ] }, "OAuth2JWKSResponse": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/JWK" } } }, "required": [ "keys" ] }, "OAuth2RevokeRequest": { "type": "object", "properties": { "token": { "type": "string" }, "token_type_hint": { "type": "string", "enum": [ "access_token", "refresh_token" ], "nullable": true }, "client_id": { "type": "string", "nullable": true }, "client_secret": { "type": "string", "nullable": true } }, "required": [ "token" ] }, "OAuth2IntrospectRequest": { "type": "object", "properties": { "token": { "type": "string" }, "token_type_hint": { "type": "string", "enum": [ "access_token", "refresh_token" ], "nullable": true }, "client_id": { "type": "string", "nullable": true }, "client_secret": { "type": "string", "nullable": true } }, "required": [ "token" ] }, "OAuth2IntrospectResponse": { "type": "object", "properties": { "active": { "type": "boolean" }, "scope": { "type": "string" }, "client_id": { "type": "string" }, "sub": { "type": "string" }, "exp": { "type": "integer" }, "iat": { "type": "integer" }, "iss": { "type": "string" }, "token_type": { "type": "string" } }, "required": [ "active" ] }, "OAuth2LoginResponse": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "type": "string", "format": "uuid" }, "clientId": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "redirectUri": { "type": "string" } }, "required": [ "requestId", "clientId", "scopes", "redirectUri" ] }, "OAuth2LoginRequest": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "type": "string", "format": "uuid" } }, "required": [ "requestId" ] }, "OAuth2LoginCompleteResponse": { "type": "object", "additionalProperties": false, "properties": { "redirectUri": { "type": "string", "format": "uri" } }, "required": [ "redirectUri" ] } }, "parameters": { "RedirectToQuery": { "in": "query", "name": "redirectTo", "description": "Target URL for the redirect", "required": true, "schema": { "description": "Target URL for the redirect", "type": "string", "format": "uri", "example": "https://my-app.com/catch-redirection" } }, "SignInProvider": { "in": "path", "name": "provider", "required": true, "description": "The name of the social provider", "schema": { "type": "string", "enum": [ "apple", "github", "google", "linkedin", "discord", "spotify", "twitch", "gitlab", "bitbucket", "workos", "azuread", "entraid", "strava", "facebook", "windowslive", "twitter" ] } }, "TicketQuery": { "in": "query", "name": "ticket", "description": "Ticket", "required": true, "schema": { "type": "string", "description": "Ticket", "example": "verifyEmail:xxxxxxxx" } }, "TicketTypeQuery": { "in": "query", "name": "type", "description": "Type of the ticket. Deprecated, no longer used", "required": false, "schema": { "type": "string", "enum": [ "emailVerify", "emailConfirmChange", "signinPasswordless", "passwordReset" ], "description": "Type of the ticket", "example": "emailVerify" }, "deprecated": true } }, "headers": { "RedirectLocation": { "description": "URL to redirect to", "schema": { "type": "string", "format": "uri" }, "required": true } } } }