{ "openapi": "3.0.0", "paths": { "/auth/signup": { "post": { "description": "Register a new user. Response format depends on accessTokenType configuration:\n- Header mode (default): Returns tokens in response body\n- Cookie mode: Sets tokens in HTTP-only cookies and returns success message", "operationId": "AuthController_signup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthSignupRequestDto" } } } }, "responses": { "200": { "description": "Header mode: Returns message + tokens in body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthWithTokensResponseDto" } } } } }, "summary": "Signup", "tags": [ "Auth" ] } }, "/auth/login": { "post": { "description": "Authenticate user. Response format depends on accessTokenType configuration:\n- Header mode (default): Returns tokens in response body\n- Cookie mode: Sets tokens in HTTP-only cookies and returns success message", "operationId": "AuthController_login", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthLoginRequestDto" } } } }, "responses": { "200": { "description": "Header mode: Returns message + tokens in body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthWithTokensResponseDto" } } } } }, "summary": "Login", "tags": [ "Auth" ] } }, "/auth/passwordless/send": { "post": { "operationId": "AuthController_passwordlessSend", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthPasswordlessSendRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponseDto" } } } } }, "summary": "Passwordless — send login code (email or SMS)", "tags": [ "Auth" ] } }, "/auth/refresh-token": { "post": { "description": "Refresh access token. Response format depends on accessTokenType configuration:\n- Header mode (default): Returns new tokens in response body\n- Cookie mode: Sets new tokens in HTTP-only cookies and returns success message", "operationId": "AuthController_refreshToken", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthRefreshTokenRequestDto" } } } }, "responses": { "200": { "description": "Header mode: Returns message + tokens in body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthWithTokensResponseDto" } } } } }, "summary": "Refresh Token", "tags": [ "Auth" ] } }, "/auth/mfa/challenge": { "post": { "operationId": "MfaController_challenge", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthSendMfaCodeRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthMfaCodeSentResponseDto" } } } } }, "summary": "Send MFA code for setup/verification", "tags": [ "Mfa" ] } }, "/auth/mfa/verify": { "post": { "description": "Verify multi-factor authentication. Response format depends on accessTokenType configuration:\n- Header mode (default): Returns tokens in response body\n- Cookie mode: Sets tokens in HTTP-only cookies and returns success message", "operationId": "AuthController_verify2fa", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthVerify2faRequestDto" } } } }, "responses": { "200": { "description": "Header mode: Returns message + tokens in body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verify2faWithTokensResponseDto" } } } } }, "summary": "Verify MFA", "tags": [ "Auth" ] } }, "/auth/logout": { "post": { "operationId": "AuthController_logout", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthLogoutResponseDto" } } } } }, "summary": "Logout", "tags": [ "Auth" ] } }, "/auth/logout-all": { "post": { "operationId": "AuthController_logoutAll", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthLogoutAllResponseDto" } } } } }, "summary": "Logout All", "tags": [ "Auth" ] } }, "/auth/switch-tenant": { "post": { "operationId": "AuthController_switchTenant", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthSwitchTenantRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthWithTokensResponseDto" } } } } }, "summary": "Switch Active Tenant", "tags": [ "Auth" ] } }, "/auth/me": { "get": { "operationId": "AuthController_sessionUserData", "parameters": [], "responses": { "200": { "description": "Current user data" } }, "summary": "Get Session User Data and menage extra user data from config", "tags": [ "Auth" ] } }, "/auth/change-password": { "post": { "operationId": "AuthController_changePassword", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthChangePasswordRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponseDto" } } } } }, "summary": "Change Password", "tags": [ "Auth" ] } }, "/auth/forgot-password": { "post": { "operationId": "AuthController_forgotPassword", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthForgotPasswordRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthPasswordResetLinkSentResponseDto" } } } } }, "summary": "Forgot password", "tags": [ "Auth" ] } }, "/auth/verify-forgot-password-otp": { "post": { "operationId": "AuthController_verifyForgotPasswordOtp", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthVerifyForgotPasswordOtpRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyOtpResponseDto" } } } } }, "summary": "Verify Forgot Password OTP and get reset token", "tags": [ "Auth" ] } }, "/auth/reset-password": { "post": { "operationId": "AuthController_resetPassword", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthResetPasswordWithTokenRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthPasswordResetResponseDto" } } } } }, "summary": "Reset password", "tags": [ "Auth" ] } }, "/auth/client-config": { "get": { "description": "Public configuration for clients (tenant mode, auth methods, registration, MFA, etc.). No auth required.", "operationId": "AuthController_getClientConfig", "parameters": [], "responses": { "200": { "description": "Client configuration" } }, "summary": "Client config", "tags": [ "Auth" ] } }, "/auth/user": { "get": { "operationId": "AuthController_getUser", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponseDto" } } } } }, "summary": "Get Logged In User", "tags": [ "Auth" ] } }, "/auth/verify-session": { "get": { "description": "Lightweight endpoint to verify if the current session is valid. Returns minimal information without fetching full user data.", "operationId": "AuthController_verifySession", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "properties": { "valid": { "type": "boolean", "example": true }, "userId": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" }, "expiresAt": { "type": "string", "example": "2024-01-01T12:00:00.000Z" } } } } } } }, "summary": "Verify Session", "tags": [ "Auth" ] } }, "/auth/send-email-verification": { "post": { "operationId": "AuthController_sendEmailVerification", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthSendEmailVerificationRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthEmailVerificationSentResponseDto" } } } } }, "summary": "Send email verification", "tags": [ "Auth" ] } }, "/auth/verify-email": { "post": { "operationId": "AuthController_verifyEmail", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthVerifyEmailRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthEmailVerifiedResponseDto" } } } } }, "summary": "Verify Email", "tags": [ "Auth" ] } }, "/auth/send-phone-verification": { "post": { "operationId": "AuthController_sendPhoneVerification", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthSendPhoneVerificationRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthPhoneVerificationSentResponseDto" } } } } }, "summary": "Send phone verification (SMS OTP)", "tags": [ "Auth" ] } }, "/auth/verify-phone": { "post": { "operationId": "AuthController_verifyPhone", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthVerifyPhoneRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthPhoneVerifiedResponseDto" } } } } }, "summary": "Verify phone number with OTP", "tags": [ "Auth" ] } }, "/auth/callback/{provider}": { "get": { "description": "OAuth callback endpoint for SSO providers. Exchanges authorization code for access token and returns raw SSO user info. Returns HTML page that posts SSO data to parent window and auto-closes.", "operationId": "AuthController_ssoCallback", "parameters": [ { "name": "provider", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "" } }, "summary": "SSO Callback", "tags": [ "Auth" ] } }, "/auth/mfa/status": { "get": { "operationId": "MfaController_getStatus", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaStatusResponseDto" } } } } }, "summary": "Get MFA status for the current user", "tags": [ "Mfa" ] } }, "/auth/mfa/toggle": { "post": { "operationId": "MfaController_toggleMfa", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthToggleMfaRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthMfaToggleResponseDto" } } } } }, "summary": "Enable or disable MFA for the current user", "tags": [ "Mfa" ] } }, "/auth/mfa/devices": { "get": { "operationId": "MfaController_listDevices", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MfaDeviceDto" } } } } } }, "summary": "List registered MFA devices", "tags": [ "Mfa" ] } }, "/auth/mfa/devices/{deviceId}": { "delete": { "operationId": "MfaController_removeDevice", "parameters": [ { "name": "deviceId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthMfaDeviceRemovedResponseDto" } } } } }, "summary": "Remove a registered MFA device", "tags": [ "Mfa" ] } }, "/auth/mfa/setup-totp": { "post": { "operationId": "MfaController_setupTotp", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Setup TOTP Device", "tags": [ "Mfa" ] } }, "/auth/mfa/verify-totp-setup": { "post": { "operationId": "MfaController_verifyTotpSetup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthVerifyTotpSetupRequestDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthMfaDeviceVerifiedResponseDto" } } } } }, "summary": "Verify TOTP Setup", "tags": [ "Mfa" ] } }, "/auth/mfa/generate-recovery-code": { "post": { "operationId": "MfaController_generateRecoveryCodes", "parameters": [], "responses": { "200": { "description": "" } }, "summary": "Generate Recovery Codes", "tags": [ "Mfa" ] } }, "/auth/mfa/reset-totp": { "post": { "operationId": "MfaController_resetTotp", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NestAuthMfaResetResponseDto" } } } } }, "summary": "Reset TOTP Device", "tags": [ "Mfa" ] } } }, "info": { "title": "@ackplus/nest-auth API", "description": "OpenAPI specification generated from the Nest Auth module", "version": "2.0.0-beta.26", "contact": {} }, "tags": [], "servers": [], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "schemas": { "NestAuthSignupRequestDto": { "type": "object", "properties": { "email": { "type": "string", "description": "User email address (required if phone not provided)", "example": "user@example.com" }, "phone": { "type": "string", "description": "User phone number (required if email not provided)", "example": "+1234567890" }, "password": { "type": "string", "description": "User password", "example": "SecurePass123!", "minLength": 8 }, "tenantId": { "type": "string", "description": "Tenant ID for multi-tenant applications", "example": "123e4567-e89b-12d3-a456-426614174000" }, "guard": { "type": "string", "description": "Guard context (e.g. admin, web, vendor) for isolation. Deprecated: use client", "example": "admin", "deprecated": true } }, "required": [ "password" ] }, "AuthWithTokensResponseDto": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "JWT access token (short-lived)", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJpYXQiOjE2OTk5OTk5OTksImV4cCI6MTY5OTk5OTk5OX0.xyz" }, "refreshToken": { "type": "string", "description": "JWT refresh token (long-lived)", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJ0eXBlIjoicmVmcmVzaCIsImlhdCI6MTY5OTk5OTk5OX0.abc" }, "message": { "type": "string", "description": "Success message (added by controller based on configuration)", "example": "Login successful" }, "isRequiresMfa": { "type": "boolean", "description": "Whether multi-factor authentication is required", "example": false }, "mfaMethods": { "type": "array", "description": "Available MFA methods when isRequiresMfa is true", "example": [ "email", "totp" ], "items": { "type": "string", "enum": [ "email", "sms", "totp" ] } }, "defaultMfaMethod": { "type": "string", "description": "Default/recommended MFA method", "example": "email", "enum": [ "email", "sms", "totp" ] }, "trustToken": { "type": "string", "description": "Trust token for trusted device verification", "example": "1234567890" } }, "required": [ "accessToken", "refreshToken", "isRequiresMfa" ] }, "EmailCredentialsDto": { "type": "object", "properties": { "email": { "type": "string", "description": "User email address", "example": "user@example.com" }, "password": { "type": "string", "description": "User password", "example": "SecurePass123!", "minLength": 8 } }, "required": [ "email", "password" ] }, "PhoneCredentialsDto": { "type": "object", "properties": { "phone": { "type": "string", "description": "User phone number", "example": "+1234567890" }, "password": { "type": "string", "description": "User password", "example": "SecurePass123!", "minLength": 8 } }, "required": [ "phone", "password" ] }, "SocialCredentialsDto": { "type": "object", "properties": { "token": { "type": "string", "description": "OAuth token or ID token from social provider", "example": "ya29.a0AfH6SMBx1234567890abcdefghijklmnop" }, "type": { "type": "string", "description": "How to interpret the supplied token. Required only for Google: `idToken` (default) verifies a Google-signed ID token client-side; `accessToken` calls Google's userinfo endpoint with a Bearer access token. Other providers (Facebook, Apple, GitHub) ignore this field.", "example": "idToken", "enum": [ "idToken", "accessToken" ], "default": "idToken" } }, "required": [ "token" ] }, "PasswordlessOtpCredentialsDto": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Email or phone (same value as in send request)", "example": "user@example.com" }, "channels": { "type": "array", "description": "Channel(s) to try in order. Use both when the client is unsure whether `identifier` is email or phone.", "example": [ "email", "sms" ], "items": { "type": "string", "enum": [ "email", "sms" ] } }, "code": { "type": "string", "description": "One-time code from email or SMS", "example": "123456" } }, "required": [ "identifier", "channels", "code" ] }, "NestAuthLoginRequestDto": { "type": "object", "properties": { "providerName": { "type": "string", "description": "Authentication provider name", "example": "email", "enum": [ "email", "phone", "passwordless", "google", "facebook", "apple", "github" ], "default": "email" }, "credentials": { "description": "Login credentials - type varies by provider", "examples": { "emailLogin": { "summary": "Email + password", "value": { "email": "user@example.com", "password": "SecurePass123!" } }, "phoneLogin": { "summary": "Phone + password", "value": { "phone": "+1234567890", "password": "SecurePass123!" } }, "passwordlessOtp": { "summary": "Passwordless OTP — set providerName to passwordless (after POST /auth/passwordless/send)", "value": { "providerName": "passwordless", "credentials": { "identifier": "user@example.com", "channels": [ "email", "sms" ], "code": "123456" } } }, "socialLogin": { "summary": "Social Login (Google/Facebook/etc)", "value": { "token": "ya29.a0AfH6SMBx...", "type": "idToken" } } }, "oneOf": [ { "$ref": "#/components/schemas/EmailCredentialsDto" }, { "$ref": "#/components/schemas/PhoneCredentialsDto" }, { "$ref": "#/components/schemas/SocialCredentialsDto" }, { "$ref": "#/components/schemas/PasswordlessOtpCredentialsDto" } ] }, "tenantId": { "type": "string", "description": "Tenant ID for multi-tenant applications", "example": "123e4567-e89b-12d3-a456-426614174000" }, "guard": { "type": "string", "description": "Guard context (e.g. admin, web, vendor) for isolation. Deprecated: use client", "example": "admin", "deprecated": true }, "createUserIfNotExists": { "type": "boolean", "description": "Auto-create user if not exists (for social auth)", "default": false } }, "required": [ "credentials" ] }, "NestAuthPasswordlessSendRequestDto": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Email or phone (per `channel`)", "example": "user@example.com" }, "channel": { "type": "string", "enum": [ "email", "sms" ] }, "tenantId": { "type": "string" } }, "required": [ "identifier", "channel" ] }, "MessageResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message" } }, "required": [ "message" ] }, "NestAuthRefreshTokenRequestDto": { "type": "object", "properties": { "refreshToken": { "type": "string", "description": "Refresh token to obtain new access token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJ0eXBlIjoicmVmcmVzaCJ9.abc123" } } }, "NestAuthMfaCodeSentResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message", "example": "MFA code sent successfully" } }, "required": [ "message" ] }, "NestAuthMFAMethodEnum": { "type": "string", "enum": [ "email", "sms", "totp" ] }, "NestAuthVerify2faRequestDto": { "type": "object", "properties": { "method": { "description": "MFA method used", "example": "totp", "allOf": [ { "$ref": "#/components/schemas/NestAuthMFAMethodEnum" } ] }, "otp": { "type": "string", "description": "One-time password code", "example": "123456", "minLength": 6, "maxLength": 8 }, "trustDevice": { "type": "boolean", "description": "Whether to trust this device for future logins", "example": true } }, "required": [ "method", "otp" ] }, "UserResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "User unique identifier", "example": "123e4567-e89b-12d3-a456-426614174000" }, "email": { "type": "string", "description": "User email address", "example": "user@example.com" }, "phone": { "type": "string", "description": "User phone number", "example": "+1234567890" }, "emailVerifiedAt": { "format": "date-time", "type": "string", "description": "Email verification status", "example": true }, "phoneVerifiedAt": { "format": "date-time", "type": "string", "description": "Phone verification status", "example": true }, "isMfaEnabled": { "type": "boolean", "description": "Whether MFA is enabled for this user", "example": false }, "roles": { "description": "User roles (role names)", "example": [ "admin", "user" ], "type": "array", "items": { "type": "string" } }, "permissions": { "description": "User permissions (flattened from roles)", "example": [ "read:users", "write:users" ], "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "description": "Additional user metadata", "example": { "firstName": "John", "lastName": "Doe" } }, "tenantId": { "type": "string", "description": "Tenant ID for multi-tenant applications", "example": "tenant-123" } }, "required": [ "id", "emailVerifiedAt", "phoneVerifiedAt" ] }, "Verify2faWithTokensResponseDto": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "JWT access token (short-lived)", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJpYXQiOjE2OTk5OTk5OTksImV4cCI6MTY5OTk5OTk5OX0.xyz" }, "refreshToken": { "type": "string", "description": "JWT refresh token (long-lived)", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJ0eXBlIjoicmVmcmVzaCIsImlhdCI6MTY5OTk5OTk5OX0.abc" }, "message": { "type": "string", "description": "Verification success message (added by controller)", "example": "2FA verification successful" }, "user": { "description": "User information with roles and permissions", "allOf": [ { "$ref": "#/components/schemas/UserResponseDto" } ] } }, "required": [ "accessToken", "refreshToken" ] }, "NestAuthLogoutResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message", "example": "Logged out successfully" } }, "required": [ "message" ] }, "NestAuthLogoutAllResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message", "example": "Logged out from all devices" } }, "required": [ "message" ] }, "NestAuthSwitchTenantRequestDto": { "type": "object", "properties": { "tenantId": { "type": "string", "description": "Tenant ID to switch into", "example": "123e4567-e89b-12d3-a456-426614174000" } }, "required": [ "tenantId" ] }, "NestAuthChangePasswordRequestDto": { "type": "object", "properties": { "currentPassword": { "type": "string", "description": "Current password", "example": "DemoOwner1!", "minLength": 8 }, "newPassword": { "type": "string", "description": "New password", "example": "DemoOwner1!New", "minLength": 8 } }, "required": [ "currentPassword", "newPassword" ] }, "NestAuthForgotPasswordRequestDto": { "type": "object", "properties": { "email": { "type": "string", "description": "User email address (required if phone not provided)", "example": "user@example.com" }, "phone": { "type": "string", "description": "User phone number (required if email not provided)", "example": "+1234567890" }, "tenantId": { "type": "string", "description": "Tenant ID for multi-tenant applications", "example": "123e4567-e89b-12d3-a456-426614174000" } } }, "NestAuthPasswordResetLinkSentResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message", "example": "If your email is registered, you will receive a password reset link" } }, "required": [ "message" ] }, "NestAuthVerifyForgotPasswordOtpRequestDto": { "type": "object", "properties": { "email": { "type": "string", "description": "User email address (required if phone not provided)", "example": "user@example.com" }, "phone": { "type": "string", "description": "User phone number (required if email not provided)", "example": "+1234567890" }, "code": { "type": "string", "description": "Verification or magic-link code (matches OTP entity `code`)", "example": "123456", "minLength": 6, "maxLength": 8 }, "tenantId": { "type": "string", "description": "Tenant ID for multi-tenant applications", "example": "123e4567-e89b-12d3-a456-426614174000" } }, "required": [ "code" ] }, "VerifyOtpResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "resetToken": { "type": "string", "description": "Password reset token - use this to reset password" } }, "required": [ "message" ] }, "NestAuthResetPasswordWithTokenRequestDto": { "type": "object", "properties": { "token": { "type": "string", "description": "Password reset token (JWT) received after OTP verification", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicGFzc3dvcmQtcmVzZXQifQ.xyz" }, "newPassword": { "type": "string", "description": "New password", "example": "NewSecurePass123!", "minLength": 8 } }, "required": [ "token", "newPassword" ] }, "NestAuthPasswordResetResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message", "example": "Password has been reset successfully" } }, "required": [ "message" ] }, "NestAuthSendEmailVerificationRequestDto": { "type": "object", "properties": { "tenantId": { "type": "string", "description": "Tenant ID for multi-tenant applications", "example": "123e4567-e89b-12d3-a456-426614174000" } } }, "NestAuthEmailVerificationSentResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message", "example": "Verification email sent" } }, "required": [ "message" ] }, "NestAuthVerifyEmailRequestDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Verification code received via email", "example": "123456", "minLength": 6, "maxLength": 8 }, "tenantId": { "type": "string", "description": "Tenant ID for multi-tenant applications", "example": "123e4567-e89b-12d3-a456-426614174000" } }, "required": [ "code" ] }, "NestAuthEmailVerifiedResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message", "example": "Email verified successfully" } }, "required": [ "message" ] }, "NestAuthSendPhoneVerificationRequestDto": { "type": "object", "properties": { "tenantId": { "type": "string", "description": "Tenant ID for multi-tenant applications", "example": "123e4567-e89b-12d3-a456-426614174000" } } }, "NestAuthPhoneVerificationSentResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message", "example": "Verification SMS sent" } }, "required": [ "message" ] }, "NestAuthVerifyPhoneRequestDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Verification code received via SMS (matches OTP entity `code`)", "example": "123456", "minLength": 6, "maxLength": 8 }, "tenantId": { "type": "string", "description": "Tenant ID for multi-tenant applications", "example": "123e4567-e89b-12d3-a456-426614174000" } }, "required": [ "code" ] }, "NestAuthPhoneVerifiedResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message", "example": "Phone verified successfully" } }, "required": [ "message" ] }, "MfaDeviceDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the MFA device", "example": "4b3c9c9c-9a9d-4d1e-8d9f-123456789abc" }, "deviceName": { "type": "string", "description": "Friendly name of the registered device", "example": "Work laptop" }, "method": { "type": "string", "description": "MFA method this device supports", "enum": [ "email", "sms", "totp" ], "example": "totp" }, "lastUsedAt": { "format": "date-time", "type": "string", "description": "Timestamp of when the device was last used", "example": "2024-05-20T12:34:56.000Z" }, "verified": { "type": "boolean", "description": "Whether the device setup has been verified", "example": true }, "createdAt": { "format": "date-time", "type": "string", "description": "Timestamp of when the device was registered", "example": "2024-05-18T10:15:00.000Z" } }, "required": [ "id", "deviceName", "method", "verified" ] }, "MfaStatusResponseDto": { "type": "object", "properties": { "isEnabled": { "type": "boolean", "description": "Whether MFA is currently enabled for the user", "example": true }, "verifiedMethods": { "type": "array", "description": "MFA methods the user has verified and can currently use (includes EMAIL/SMS if configured, and TOTP if user has verified device)", "example": [ "email", "totp" ], "items": { "type": "string", "enum": [ "email", "sms", "totp" ] } }, "configuredMethods": { "type": "array", "description": "All MFA methods configured and available in the application (methods user can potentially set up)", "example": [ "email", "totp", "sms" ], "items": { "type": "string", "enum": [ "email", "sms", "totp" ] } }, "allowUserToggle": { "type": "boolean", "description": "Indicates if MFA toggling is allowed for the user", "example": true }, "allowMethodSelection": { "type": "boolean", "description": "Indicates if users can choose their preferred MFA method", "example": true }, "totpDevices": { "description": "Registered TOTP devices for the user", "type": "array", "items": { "$ref": "#/components/schemas/MfaDeviceDto" } }, "hasRecoveryCode": { "type": "boolean", "description": "Whether a recovery code has been generated for the user", "example": false }, "required": { "type": "boolean", "description": "Whether MFA is required for all users. If true, users cannot disable MFA even if allowUserToggle is true", "example": false }, "canToggle": { "type": "boolean", "description": "Whether the user can toggle MFA. This is false if MFA is required (required=true) even if allowUserToggle is true", "example": true } }, "required": [ "isEnabled", "verifiedMethods", "configuredMethods", "allowUserToggle", "allowMethodSelection", "totpDevices", "hasRecoveryCode", "required", "canToggle" ] }, "NestAuthToggleMfaRequestDto": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether MFA should be enabled for the current user", "example": true } }, "required": [ "enabled" ] }, "NestAuthMfaToggleResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message", "example": "MFA enabled successfully" } }, "required": [ "message" ] }, "NestAuthMfaDeviceRemovedResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message", "example": "Device removed successfully" } }, "required": [ "message" ] }, "NestAuthSendMfaCodeRequestDto": { "type": "object", "properties": { "method": { "description": "MFA delivery method", "example": "email", "examples": { "email": { "value": "email", "description": "Send OTP via email" }, "sms": { "value": "sms", "description": "Send OTP via SMS" }, "totp": { "value": "totp", "description": "Use authenticator app (TOTP)" } }, "allOf": [ { "$ref": "#/components/schemas/NestAuthMFAMethodEnum" } ] } }, "required": [ "method" ] }, "NestAuthVerifyTotpSetupRequestDto": { "type": "object", "properties": { "otp": { "type": "string", "description": "The TOTP code from authenticator app", "example": "123456", "minLength": 6, "maxLength": 6 }, "secret": { "type": "string", "description": "Secret key from TOTP setup", "example": "JBSWY3DPEHPK3PXP" } }, "required": [ "otp", "secret" ] }, "NestAuthMfaDeviceVerifiedResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message", "example": "Device setup successfully" } }, "required": [ "message" ] }, "NestAuthMfaResetResponseDto": { "type": "object", "properties": { "message": { "type": "string", "description": "Response message", "example": "MFA reset successfully" } }, "required": [ "message" ] } } } }