{ "openapi": "3.0.3", "info": { "title": "FIVUCSAS Identity Core API", "description": "Face and Identity Verification Using Cloud-based SaaS - Identity Core API. Multi-tenant biometric authentication platform with OAuth 2.0/OIDC, N-step MFA, WebAuthn/FIDO2, and identity verification pipeline.", "version": "1.0.0", "contact": { "name": "FIVUCSAS", "url": "https://fivucsas.com" } }, "servers": [ { "url": "https://api.fivucsas.com/api/v1", "description": "Production API (all /api/v1/* endpoints)" }, { "url": "https://api.fivucsas.com", "description": "Root (OIDC discovery endpoints only)" } ], "tags": [ { "name": "Authentication", "description": "Login, register, MFA, 2FA, password reset, email/phone verification" }, { "name": "Users", "description": "User CRUD, profile, settings, guest management" }, { "name": "Enrollment", "description": "Biometric enrollment management and liveness verification" }, { "name": "Auth Flows", "description": "Tenant auth flow configuration (N-step MFA)" }, { "name": "Sessions", "description": "Auth session execution and cross-device session management" }, { "name": "OAuth 2.0", "description": "OAuth 2.0 authorization code flow, token exchange, OIDC userinfo" }, { "name": "OAuth 2.0 Clients", "description": "OAuth 2.0 client application CRUD" }, { "name": "OpenID Connect", "description": "OIDC discovery and JWKS endpoints" }, { "name": "WebAuthn", "description": "FIDO2/WebAuthn credential registration and authentication" }, { "name": "Biometric", "description": "Face, fingerprint, and voice biometric enrollment and verification" }, { "name": "Verification", "description": "Identity verification pipeline (KYC, document scan, liveness)" }, { "name": "Tenants", "description": "Multi-tenant management" }, { "name": "Roles", "description": "Role and permission management, user-role assignment" }, { "name": "Audit", "description": "Audit log and system statistics" }, { "name": "OTP", "description": "Email/SMS OTP and TOTP setup and verification" }, { "name": "QR Authentication", "description": "QR code generation and cross-device login sessions" }, { "name": "NFC", "description": "NFC card enrollment and verification" }, { "name": "Devices", "description": "Device management and step-up authentication" }, { "name": "Auth Methods", "description": "Auth method listing and tenant method configuration" }, { "name": "Admin Overview", "description": "Cross-tenant admin overview endpoints" }, { "name": "System", "description": "Health check and system statistics" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "LoginRequest": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "clientId": { "type": "string" } } }, "RegisterRequest": { "type": "object", "required": ["email", "password", "firstName", "lastName"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } } }, "RefreshTokenRequest": { "type": "object", "required": ["refreshToken"], "properties": { "refreshToken": { "type": "string" } } }, "AuthResponse": { "type": "object", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "expiresIn": { "type": "integer", "format": "int64" }, "user": { "$ref": "#/components/schemas/UserResponse" }, "twoFactorRequired": { "type": "boolean" }, "twoFactorMethod": { "type": "string" }, "mfaSessionToken": { "type": "string" }, "totalSteps": { "type": "integer" }, "currentStep": { "type": "integer" }, "availableMethods": { "type": "array", "items": { "$ref": "#/components/schemas/AvailableMfaMethod" } } } }, "AvailableMfaMethod": { "type": "object", "properties": { "methodType": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "enrolled": { "type": "boolean" }, "preferred": { "type": "boolean" }, "requiresEnrollment": { "type": "boolean" } } }, "UserResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" }, "address": { "type": "string" }, "role": { "type": "string" }, "tenantId": { "type": "string", "format": "uuid" }, "active": { "type": "boolean" }, "emailVerified": { "type": "boolean" }, "phoneVerified": { "type": "boolean" } } }, "CreateUserRequest": { "type": "object", "required": ["email", "password", "firstName", "lastName"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" }, "address": { "type": "string" }, "idNumber": { "type": "string" }, "role": { "type": "string" }, "tenantId": { "type": "string" } } }, "UpdateUserRequest": { "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "phoneNumber": { "type": "string" }, "address": { "type": "string" } } }, "ChangePasswordRequest": { "type": "object", "required": ["currentPassword", "newPassword"], "properties": { "currentPassword": { "type": "string" }, "newPassword": { "type": "string" } } }, "PaginatedResponse": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object" } }, "totalElements": { "type": "integer", "format": "int64" }, "totalPages": { "type": "integer" }, "page": { "type": "integer" }, "size": { "type": "integer" } } }, "EnrollmentDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "userName": { "type": "string" }, "userEmail": { "type": "string" }, "tenantId": { "type": "string", "format": "uuid" }, "authMethodType": { "type": "string" }, "status": { "type": "string", "enum": ["NOT_STARTED", "IN_PROGRESS", "ENROLLED", "FAILED"] }, "enrolledAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time" } } }, "EnrollmentResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "methodType": { "type": "string" }, "status": { "type": "string" } } }, "AuthFlowResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "operationType": { "type": "string" }, "isDefault": { "type": "boolean" }, "isActive": { "type": "boolean" }, "stepCount": { "type": "integer" }, "steps": { "type": "array", "items": { "type": "object" } } } }, "CreateAuthFlowCommand": { "type": "object", "properties": { "name": { "type": "string" }, "operationType": { "type": "string" }, "isDefault": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "object" } } } }, "UpdateAuthFlowCommand": { "type": "object", "properties": { "name": { "type": "string" }, "isDefault": { "type": "boolean" }, "isActive": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "object" } } } }, "AuthSessionResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "currentStep": { "type": "integer" }, "totalSteps": { "type": "integer" } } }, "StartAuthSessionCommand": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "flowId": { "type": "string", "format": "uuid" } } }, "CompleteAuthStepCommand": { "type": "object", "properties": { "methodType": { "type": "string" }, "data": { "type": "object" } } }, "StepResultResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "SessionResponse": { "type": "object", "properties": { "id": { "type": "string" }, "deviceInfo": { "type": "string" }, "ipAddress": { "type": "string" }, "lastActive": { "type": "string", "format": "date-time" }, "current": { "type": "boolean" } } }, "TenantResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "contactEmail": { "type": "string" }, "contactPhone": { "type": "string" }, "maxUsers": { "type": "integer" }, "biometricEnabled": { "type": "boolean" }, "sessionTimeoutMinutes": { "type": "integer" }, "refreshTokenValidityDays": { "type": "integer" }, "mfaRequired": { "type": "boolean" }, "status": { "type": "string" } } }, "CreateTenantRequest": { "type": "object", "required": ["name", "slug"], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "slug": { "type": "string", "minLength": 2, "maxLength": 50 }, "description": { "type": "string", "maxLength": 500 }, "contactEmail": { "type": "string", "format": "email" }, "contactPhone": { "type": "string" }, "maxUsers": { "type": "integer", "minimum": 1 }, "biometricEnabled": { "type": "boolean" }, "sessionTimeoutMinutes": { "type": "integer", "minimum": 1 }, "refreshTokenValidityDays": { "type": "integer", "minimum": 1 }, "mfaRequired": { "type": "boolean" } } }, "UpdateTenantRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "contactEmail": { "type": "string", "format": "email" }, "contactPhone": { "type": "string" }, "maxUsers": { "type": "integer", "minimum": 1 }, "biometricEnabled": { "type": "boolean" }, "sessionTimeoutMinutes": { "type": "integer", "minimum": 1 }, "refreshTokenValidityDays": { "type": "integer", "minimum": 1 }, "mfaRequired": { "type": "boolean" } } }, "AuditLogDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "entityType": { "type": "string" }, "entityId": { "type": "string" }, "success": { "type": "boolean" }, "errorMessage": { "type": "string" }, "ipAddress": { "type": "string" }, "userAgent": { "type": "string" }, "details": { "type": "object" }, "timestamp": { "type": "string", "format": "date-time" } } }, "StatisticsDto": { "type": "object", "properties": { "totalUsers": { "type": "integer", "format": "int64" }, "activeUsers": { "type": "integer", "format": "int64" }, "inactiveUsers": { "type": "integer", "format": "int64" }, "suspendedUsers": { "type": "integer", "format": "int64" }, "biometricEnrolledUsers": { "type": "integer", "format": "int64" }, "totalVerifications": { "type": "integer", "format": "int64" }, "averageVerificationsPerUser": { "type": "number", "format": "double" }, "totalTenants": { "type": "integer", "format": "int64" }, "pendingEnrollments": { "type": "integer", "format": "int64" }, "successfulEnrollments": { "type": "integer", "format": "int64" }, "failedEnrollments": { "type": "integer", "format": "int64" }, "authSuccessRate": { "type": "number", "format": "double" }, "verificationSuccessRate": { "type": "number", "format": "double" } } }, "BiometricVerificationResponse": { "type": "object", "properties": { "verified": { "type": "boolean" }, "confidence": { "type": "number", "format": "double" }, "message": { "type": "string" } } }, "VerificationSessionResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "flowId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object" } } } }, "CreateVerificationSessionCommand": { "type": "object", "required": ["userId", "tenantId", "flowId"], "properties": { "userId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "flowId": { "type": "string", "format": "uuid" } } }, "SubmitVerificationStepCommand": { "type": "object", "properties": { "data": { "type": "object" } } }, "ReviewVerificationStepCommand": { "type": "object", "properties": { "approved": { "type": "boolean" }, "notes": { "type": "string" } } }, "VerificationStepResultResponse": { "type": "object", "properties": { "stepNumber": { "type": "integer" }, "status": { "type": "string" }, "data": { "type": "object" } } }, "VerificationStatusResponse": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "sessions": { "type": "array", "items": { "type": "object" } } } }, "IndustryTemplateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object" } } } }, "RoleResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "tenantId": { "type": "string", "format": "uuid" }, "systemRole": { "type": "boolean" }, "active": { "type": "boolean" }, "permissions": { "type": "array", "items": { "type": "object" } } } }, "CreateRoleRequest": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "tenantId": { "type": "string" }, "permissionIds": { "type": "array", "items": { "type": "string" } } } }, "UpdateRoleRequest": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "active": { "type": "boolean" } } }, "PermissionResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "resource": { "type": "string" }, "action": { "type": "string" } } }, "RegisterClientRequest": { "type": "object", "required": ["appName", "redirectUris"], "properties": { "appName": { "type": "string", "minLength": 1, "maxLength": 255 }, "redirectUris": { "type": "string", "description": "Comma-separated redirect URIs" }, "scopes": { "type": "array", "items": { "type": "string" }, "default": ["openid"] } } }, "OAuth2ClientResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "appName": { "type": "string" }, "clientId": { "type": "string" }, "redirectUris": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": ["ACTIVE", "INACTIVE"] }, "createdAt": { "type": "string", "format": "date-time" } } }, "OAuth2ClientCreatedResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "appName": { "type": "string" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string", "description": "Plaintext secret, shown only once" }, "redirectUris": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "DeviceResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "platform": { "type": "string" }, "deviceName": { "type": "string" } } }, "RegisterDeviceCommand": { "type": "object", "properties": { "keyId": { "type": "string" }, "platform": { "type": "string", "enum": ["WEB", "ANDROID", "IOS", "DESKTOP"] }, "publicKeyJwk": { "type": "object" } } }, "GuestInvitationResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "status": { "type": "string" }, "accessDurationHours": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } }, "InviteGuestRequest": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" }, "accessDurationHours": { "type": "integer" }, "message": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "status": { "type": "integer" }, "error": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "string" } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/auth/register": { "post": { "operationId": "register", "summary": "Register a new user", "tags": ["Authentication"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } } }, "responses": { "201": { "description": "User registered successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/login": { "post": { "operationId": "login", "summary": "Login with email and password", "tags": ["Authentication"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Login successful (may return mfaSessionToken if MFA required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "401": { "description": "Invalid credentials" } } } }, "/auth/refresh": { "post": { "operationId": "refreshToken", "summary": "Refresh access token using refresh token", "tags": ["Authentication"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" } } } }, "responses": { "200": { "description": "Token refreshed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "401": { "description": "Invalid or expired refresh token" } } } }, "/auth/logout": { "post": { "operationId": "logout", "summary": "Logout and revoke refresh token", "tags": ["Authentication"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshTokenRequest" } } } }, "responses": { "204": { "description": "Logged out successfully" }, "401": { "description": "Not authenticated" } } } }, "/auth/me": { "get": { "operationId": "getCurrentUser", "summary": "Get current authenticated user", "tags": ["Authentication"], "responses": { "200": { "description": "Current user info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Not authenticated" } } } }, "/auth/forgot-password": { "post": { "operationId": "forgotPassword", "summary": "Request a password reset code via email", "tags": ["Authentication"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Reset code sent (always returns success to prevent email enumeration)" }, "429": { "description": "Rate limit exceeded" } } } }, "/auth/reset-password": { "post": { "operationId": "resetPassword", "summary": "Reset password using the code from email", "tags": ["Authentication"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "code", "newPassword"], "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string" }, "newPassword": { "type": "string" } } } } } }, "responses": { "200": { "description": "Password reset successfully" }, "400": { "description": "Invalid email, code, or password complexity" } } } }, "/auth/send-email-verification": { "post": { "operationId": "sendEmailVerification", "summary": "Send email verification code", "tags": ["Authentication"], "responses": { "200": { "description": "Verification code sent" }, "401": { "description": "Not authenticated" } } } }, "/auth/verify-email": { "post": { "operationId": "verifyEmail", "summary": "Verify email address using OTP code", "tags": ["Authentication"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "Email verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "description": "Code is required" } } } }, "/auth/send-phone-verification": { "post": { "operationId": "sendPhoneVerification", "summary": "Send phone verification code via SMS", "tags": ["Authentication"], "responses": { "200": { "description": "Verification code sent" }, "400": { "description": "No phone number configured" } } } }, "/auth/verify-phone": { "post": { "operationId": "verifyPhone", "summary": "Verify phone number using OTP code", "tags": ["Authentication"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "Phone verification result" }, "400": { "description": "Code is required" } } } }, "/auth/2fa/send": { "post": { "operationId": "send2FACode", "summary": "Send 2FA verification code to user's email", "tags": ["Authentication"], "responses": { "200": { "description": "2FA code sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "email": { "type": "string" } } } } } } } } }, "/auth/2fa/verify": { "post": { "operationId": "verify2FACode", "summary": "Verify 2FA code to complete login", "tags": ["Authentication"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "2FA verification result" } } } }, "/auth/2fa/verify-method": { "post": { "operationId": "verify2FAMethod", "summary": "Verify 2FA using any supported auth method", "tags": ["Authentication"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["method"], "properties": { "method": { "type": "string", "enum": ["TOTP", "SMS_OTP", "FACE", "VOICE", "FINGERPRINT", "HARDWARE_KEY", "QR_CODE", "EMAIL_OTP"] }, "data": { "type": "object" } } } } } }, "responses": { "200": { "description": "2FA method verification result" } } } }, "/auth/2fa/send-sms": { "post": { "operationId": "send2FASms", "summary": "Send 2FA verification code via SMS", "tags": ["Authentication"], "responses": { "200": { "description": "SMS code sent" }, "400": { "description": "No phone number on file" } } } }, "/auth/my/2fa-status": { "get": { "operationId": "get2FAStatus", "summary": "Check if the current user's tenant requires 2FA", "tags": ["Authentication"], "responses": { "200": { "description": "2FA status", "content": { "application/json": { "schema": { "type": "object", "properties": { "twoFactorRequired": { "type": "boolean" }, "flowName": { "type": "string" }, "stepCount": { "type": "integer" } } } } } } } } }, "/auth/mfa/step": { "post": { "operationId": "verifyMfaStep", "summary": "Verify an MFA step (public - no JWT required, uses session token)", "tags": ["Authentication"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sessionToken", "method"], "properties": { "sessionToken": { "type": "string" }, "method": { "type": "string", "enum": ["PASSWORD", "EMAIL_OTP", "SMS_OTP", "TOTP", "FACE", "VOICE", "FINGERPRINT", "HARDWARE_KEY", "QR_CODE", "NFC_DOCUMENT"] }, "data": { "type": "object" } } } } } }, "responses": { "200": { "description": "MFA step result. Status is STEP_COMPLETED (more steps remain) or AUTHENTICATED (all steps done, JWT issued)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["STEP_COMPLETED", "AUTHENTICATED", "FAILED", "ERROR"] }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "mfaSessionToken": { "type": "string" }, "currentStep": { "type": "integer" }, "totalSteps": { "type": "integer" }, "availableMethods": { "type": "array", "items": { "$ref": "#/components/schemas/AvailableMfaMethod" } } } } } } }, "401": { "description": "Invalid or expired MFA session" } } } }, "/auth/mfa/qr-generate": { "post": { "operationId": "generateMfaQrToken", "summary": "Generate QR token during MFA flow (public, uses session token)", "tags": ["Authentication"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sessionToken"], "properties": { "sessionToken": { "type": "string" } } } } } }, "responses": { "200": { "description": "QR token generated" }, "401": { "description": "Invalid or expired MFA session" } } } }, "/auth/mfa/send-otp": { "post": { "operationId": "sendMfaOtp", "summary": "Send OTP during MFA flow (public, uses session token)", "tags": ["Authentication"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sessionToken"], "properties": { "sessionToken": { "type": "string" }, "method": { "type": "string", "enum": ["EMAIL_OTP", "SMS_OTP"], "default": "EMAIL_OTP" } } } } } }, "responses": { "200": { "description": "OTP sent" }, "401": { "description": "Invalid or expired MFA session" } } } }, "/auth/health": { "get": { "operationId": "authHealth", "summary": "Health check", "tags": ["System"], "security": [], "responses": { "200": { "description": "Auth service is healthy", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/users": { "get": { "operationId": "getAllUsers", "summary": "Get all users (paginated)", "tags": ["Users"], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "size", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated user list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse" } } } }, "403": { "description": "Insufficient permissions" } } }, "post": { "operationId": "createUser", "summary": "Create new user", "tags": ["Users"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" } } } }, "responses": { "201": { "description": "User created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "400": { "description": "Validation error" }, "403": { "description": "Insufficient permissions" } } } }, "/users/{id}": { "get": { "operationId": "getUserById", "summary": "Get user by ID", "tags": ["Users"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "404": { "description": "User not found" } } }, "put": { "operationId": "updateUser", "summary": "Update user", "tags": ["Users"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" } } } }, "responses": { "200": { "description": "User updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "404": { "description": "User not found" } } }, "delete": { "operationId": "deleteUser", "summary": "Delete user", "tags": ["Users"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "User deleted" }, "404": { "description": "User not found" } } } }, "/users/{id}/change-password": { "post": { "operationId": "changePassword", "summary": "Change user password", "tags": ["Users"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } } }, "responses": { "204": { "description": "Password changed" }, "400": { "description": "Validation error" } } } }, "/users/search": { "get": { "operationId": "searchUsers", "summary": "Search users", "tags": ["Users"], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserResponse" } } } } } } } }, "/users/{userId}/settings": { "get": { "operationId": "getUserSettings", "summary": "Get user settings", "tags": ["Users"], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User settings", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "put": { "operationId": "updateUserSettings", "summary": "Update user settings", "tags": ["Users"], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Settings updated", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/users/{userId}/settings/notifications": { "get": { "operationId": "getNotificationSettings", "summary": "Get notification settings", "tags": ["Users"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Notification settings" } } }, "put": { "operationId": "updateNotificationSettings", "summary": "Update notification settings", "tags": ["Users"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Notification settings updated" } } } }, "/users/{userId}/settings/security": { "get": { "operationId": "getSecuritySettings", "summary": "Get security settings", "tags": ["Users"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Security settings" } } }, "put": { "operationId": "updateSecuritySettings", "summary": "Update security settings", "tags": ["Users"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Security settings updated" } } } }, "/users/{userId}/settings/appearance": { "get": { "operationId": "getAppearanceSettings", "summary": "Get appearance settings", "tags": ["Users"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Appearance settings" } } }, "put": { "operationId": "updateAppearanceSettings", "summary": "Update appearance settings", "tags": ["Users"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Appearance settings updated" } } } }, "/guests/invite": { "post": { "operationId": "inviteGuest", "summary": "Invite a guest user", "tags": ["Users"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteGuestRequest" } } } }, "responses": { "201": { "description": "Guest invited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuestInvitationResponse" } } } }, "403": { "description": "Insufficient permissions" } } } }, "/guests/accept": { "post": { "operationId": "acceptInvitation", "summary": "Accept a guest invitation", "tags": ["Users"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["token", "firstName", "lastName", "password"], "properties": { "token": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "password": { "type": "string" } } } } } }, "responses": { "201": { "description": "Invitation accepted" }, "400": { "description": "Invalid token" } } } }, "/guests": { "get": { "operationId": "listInvitations", "summary": "List guest invitations for current tenant", "tags": ["Users"], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Guest invitations list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GuestInvitationResponse" } } } } } } } }, "/guests/count": { "get": { "operationId": "countActiveGuests", "summary": "Count active guests in tenant", "tags": ["Users"], "responses": { "200": { "description": "Active guest count", "content": { "application/json": { "schema": { "type": "integer", "format": "int64" } } } } } } }, "/guests/{guestUserId}/revoke": { "post": { "operationId": "revokeGuestAccess", "summary": "Revoke guest access", "tags": ["Users"], "parameters": [{ "name": "guestUserId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "204": { "description": "Guest access revoked" } } } }, "/guests/{guestUserId}/extend": { "post": { "operationId": "extendGuestAccess", "summary": "Extend guest access duration", "tags": ["Users"], "parameters": [{ "name": "guestUserId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "additionalHours": { "type": "integer" } } } } } }, "responses": { "204": { "description": "Guest access extended" } } } }, "/enrollments": { "get": { "operationId": "getAllEnrollments", "summary": "Get all enrollments", "tags": ["Enrollment"], "responses": { "200": { "description": "All enrollments", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnrollmentDto" } } } } } } } }, "/enrollments/{id}": { "get": { "operationId": "getEnrollmentById", "summary": "Get enrollment by ID", "tags": ["Enrollment"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Enrollment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentDto" } } } }, "404": { "description": "Enrollment not found" } } }, "delete": { "operationId": "deleteEnrollment", "summary": "Delete an enrollment", "tags": ["Enrollment"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "204": { "description": "Enrollment deleted" } } } }, "/enrollments/{id}/retry": { "post": { "operationId": "retryEnrollment", "summary": "Retry a failed enrollment", "tags": ["Enrollment"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Enrollment retried", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentDto" } } } }, "400": { "description": "Only failed enrollments can be retried" } } } }, "/users/{userId}/enrollments": { "get": { "operationId": "getUserEnrollments", "summary": "Get user enrollments", "tags": ["Enrollment"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "User enrollments", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnrollmentResponse" } } } } } } }, "post": { "operationId": "startEnrollment", "summary": "Start enrollment for a user", "tags": ["Enrollment"], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenantId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "methodType", "in": "query", "required": true, "schema": { "type": "string", "enum": ["PASSWORD", "EMAIL_OTP", "SMS_OTP", "TOTP", "FACE", "VOICE", "FINGERPRINT", "HARDWARE_KEY", "QR_CODE", "NFC_DOCUMENT"] } } ], "responses": { "201": { "description": "Enrollment started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentResponse" } } } } } } }, "/users/{userId}/enrollments/{methodType}/complete": { "put": { "operationId": "completeEnrollment", "summary": "Complete enrollment for a user", "tags": ["Enrollment"], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "methodType", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Enrollment completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentResponse" } } } } } } }, "/users/{userId}/enrollments/{methodType}": { "delete": { "operationId": "revokeEnrollment", "summary": "Revoke enrollment for a user", "tags": ["Enrollment"], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "methodType", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Enrollment revoked" } } } }, "/users/{userId}/enrollments/health": { "get": { "operationId": "getEnrollmentHealth", "summary": "Validate enrollment health against actual backing data", "tags": ["Enrollment"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Enrollment health status", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "methods": { "type": "object" }, "validCount": { "type": "integer" }, "totalCount": { "type": "integer" } } } } } } } } }, "/enrollment/submit": { "post": { "operationId": "submitEnrollment", "summary": "Submit enrollment with face image and identity information", "tags": ["Enrollment"], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["nationalId", "dateOfBirth", "fullName", "livenessToken", "livenessScore", "faceImage"], "properties": { "nationalId": { "type": "string" }, "dateOfBirth": { "type": "string" }, "fullName": { "type": "string" }, "livenessToken": { "type": "string" }, "livenessScore": { "type": "string" }, "faceImage": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Enrollment result" } } } }, "/enrollment/status": { "get": { "operationId": "getEnrollmentStatus", "summary": "Get current user's enrollment status", "tags": ["Enrollment"], "responses": { "200": { "description": "Enrollment status" } } } }, "/enrollment/liveness/challenge": { "post": { "operationId": "requestLivenessChallenge", "summary": "Request a liveness challenge for enrollment verification", "tags": ["Enrollment"], "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Liveness challenge created" } } } }, "/enrollment/liveness/verify": { "post": { "operationId": "verifyLiveness", "summary": "Verify liveness challenge with captured frames", "tags": ["Enrollment"], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["challengeId", "frame_0"], "properties": { "challengeId": { "type": "string" }, "frame_0": { "type": "string", "format": "binary" }, "frame_1": { "type": "string", "format": "binary" }, "frame_2": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Liveness verification result" } } } }, "/tenants/{tenantId}/auth-flows": { "get": { "operationId": "getFlows", "summary": "List auth flows for a tenant", "tags": ["Auth Flows"], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operationType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["APP_LOGIN", "WIDGET_LOGIN", "STEP_UP", "ENROLLMENT", "VERIFICATION"] } } ], "responses": { "200": { "description": "Auth flows list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuthFlowResponse" } } } } } } }, "post": { "operationId": "createFlow", "summary": "Create a new auth flow", "tags": ["Auth Flows"], "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAuthFlowCommand" } } } }, "responses": { "201": { "description": "Auth flow created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthFlowResponse" } } } } } } }, "/tenants/{tenantId}/auth-flows/{flowId}": { "get": { "operationId": "getFlow", "summary": "Get auth flow by ID", "tags": ["Auth Flows"], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Auth flow details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthFlowResponse" } } } }, "404": { "description": "Auth flow not found" } } }, "put": { "operationId": "updateFlow", "summary": "Update an auth flow", "tags": ["Auth Flows"], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAuthFlowCommand" } } } }, "responses": { "200": { "description": "Auth flow updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthFlowResponse" } } } } } }, "delete": { "operationId": "deleteFlow", "summary": "Delete an auth flow", "tags": ["Auth Flows"], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "flowId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Auth flow deleted" } } } }, "/auth/sessions": { "post": { "operationId": "startSession", "summary": "Start a new auth session", "tags": ["Sessions"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartAuthSessionCommand" } } } }, "responses": { "201": { "description": "Auth session started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponse" } } } } } } }, "/auth/sessions/{sessionId}": { "get": { "operationId": "getSession", "summary": "Get auth session status", "tags": ["Sessions"], "parameters": [{ "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Auth session status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponse" } } } } } } }, "/auth/sessions/{sessionId}/steps/{stepOrder}": { "post": { "operationId": "completeStep", "summary": "Complete an auth session step", "tags": ["Sessions"], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "stepOrder", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteAuthStepCommand" } } } }, "responses": { "200": { "description": "Step result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepResultResponse" } } } } } } }, "/auth/sessions/{sessionId}/steps/{stepOrder}/skip": { "post": { "operationId": "skipStep", "summary": "Skip an auth session step", "tags": ["Sessions"], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "stepOrder", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Step skipped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StepResultResponse" } } } } } } }, "/auth/sessions/{sessionId}/cancel": { "post": { "operationId": "cancelSession", "summary": "Cancel an auth session", "tags": ["Sessions"], "parameters": [{ "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "204": { "description": "Session cancelled" } } } }, "/auth/sessions/my": { "get": { "operationId": "getActiveSessions", "summary": "Get all active sessions for authenticated user", "tags": ["Sessions"], "parameters": [ { "name": "currentTokenId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Active sessions list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionResponse" } } } } } } } }, "/auth/sessions/my/{sessionId}": { "delete": { "operationId": "revokeSession", "summary": "Revoke a specific session (logout that device)", "tags": ["Sessions"], "parameters": [{ "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "204": { "description": "Session revoked" } } } }, "/auth/sessions/my/all": { "delete": { "operationId": "revokeAllSessions", "summary": "Revoke all other sessions (logout from all other devices)", "tags": ["Sessions"], "parameters": [ { "name": "currentTokenId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "All other sessions revoked" } } } }, "/oauth2/authorize": { "get": { "operationId": "authorize", "summary": "Initiate OAuth 2.0 authorization code flow", "tags": ["OAuth 2.0"], "security": [], "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "response_type", "in": "query", "schema": { "type": "string", "default": "code" } }, { "name": "scope", "in": "query", "schema": { "type": "string", "default": "openid profile email" } }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "nonce", "in": "query", "schema": { "type": "string" } }, { "name": "code_challenge", "in": "query", "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "schema": { "type": "string", "default": "S256" } } ], "responses": { "200": { "description": "Authorization code or auth session info" }, "400": { "description": "Invalid request" } } } }, "/oauth2/token": { "post": { "operationId": "token", "summary": "Exchange authorization code for tokens", "tags": ["OAuth 2.0"], "security": [], "parameters": [ { "name": "grant_type", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "client_secret", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "code_verifier", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Token response (access_token, id_token, refresh_token)", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "id_token": { "type": "string" }, "refresh_token": { "type": "string" } } } } } }, "400": { "description": "Invalid grant or client" } } } }, "/oauth2/userinfo": { "get": { "operationId": "userInfo", "summary": "Get authenticated user info (OIDC UserInfo)", "tags": ["OAuth 2.0"], "responses": { "200": { "description": "User claims", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Invalid or expired token" } } } }, "/oauth2/clients": { "get": { "operationId": "listOAuth2Clients", "summary": "List all OAuth2 clients for the authenticated user's tenant", "tags": ["OAuth 2.0 Clients"], "responses": { "200": { "description": "OAuth2 clients list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OAuth2ClientResponse" } } } } } } }, "post": { "operationId": "registerOAuth2Client", "summary": "Register a new OAuth2 client (returns client_secret in plaintext once)", "tags": ["OAuth 2.0 Clients"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterClientRequest" } } } }, "responses": { "201": { "description": "Client registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ClientCreatedResponse" } } } } } } }, "/oauth2/clients/{id}": { "get": { "operationId": "getOAuth2Client", "summary": "Get OAuth2 client details (secret is masked)", "tags": ["OAuth 2.0 Clients"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Client details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ClientResponse" } } } }, "404": { "description": "Client not found" } } }, "delete": { "operationId": "deleteOAuth2Client", "summary": "Delete an OAuth2 client", "tags": ["OAuth 2.0 Clients"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "204": { "description": "Client deleted" } } } }, "/oauth2/clients/{id}/status": { "patch": { "operationId": "toggleOAuth2ClientStatus", "summary": "Toggle active/inactive status of an OAuth2 client", "tags": ["OAuth 2.0 Clients"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Status updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuth2ClientResponse" } } } } } } }, "/verification/sessions": { "post": { "operationId": "createVerificationSession", "summary": "Create a new verification session", "tags": ["Verification"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVerificationSessionCommand" } } } }, "responses": { "201": { "description": "Verification session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSessionResponse" } } } } } } }, "/verification/sessions/{id}": { "get": { "operationId": "getVerificationSession", "summary": "Get verification session status", "tags": ["Verification"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Verification session details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSessionResponse" } } } } } } }, "/verification/sessions/{id}/steps/{stepNumber}": { "post": { "operationId": "submitVerificationStep", "summary": "Submit a verification step result", "tags": ["Verification"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "stepNumber", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitVerificationStepCommand" } } } }, "responses": { "200": { "description": "Step result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationStepResultResponse" } } } } } } }, "/verification/sessions/{id}/steps/{stepNumber}/review": { "post": { "operationId": "reviewVerificationStep", "summary": "Review a verification step (admin)", "tags": ["Verification"], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "stepNumber", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewVerificationStepCommand" } } } }, "responses": { "200": { "description": "Review result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationStepResultResponse" } } } }, "403": { "description": "Requires SUPER_ADMIN, ADMIN, or TENANT_ADMIN role" } } } }, "/verification/sessions/{id}/complete": { "post": { "operationId": "completeVerificationSession", "summary": "Complete a verification session", "tags": ["Verification"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Session completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSessionResponse" } } } } } } }, "/verification/templates": { "get": { "operationId": "getVerificationTemplates", "summary": "Get industry verification templates", "tags": ["Verification"], "responses": { "200": { "description": "Industry templates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IndustryTemplateResponse" } } } } } } } }, "/verification/results/{userId}": { "get": { "operationId": "getUserVerificationStatus", "summary": "Get user verification status", "tags": ["Verification"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Verification status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationStatusResponse" } } } } } } }, "/tenants": { "get": { "operationId": "getAllTenants", "summary": "Get all tenants (paginated)", "tags": ["Tenants"], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "size", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Paginated tenant list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse" } } } } } }, "post": { "operationId": "createTenant", "summary": "Create a new tenant (root only)", "tags": ["Tenants"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTenantRequest" } } } }, "responses": { "201": { "description": "Tenant created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantResponse" } } } }, "403": { "description": "Root access required" } } } }, "/tenants/{tenantId}": { "get": { "operationId": "getTenantById", "summary": "Get tenant by ID", "tags": ["Tenants"], "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Tenant details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantResponse" } } } }, "404": { "description": "Tenant not found" } } }, "put": { "operationId": "updateTenant", "summary": "Update tenant configuration", "tags": ["Tenants"], "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTenantRequest" } } } }, "responses": { "200": { "description": "Tenant updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantResponse" } } } } } }, "delete": { "operationId": "deleteTenant", "summary": "Delete tenant (root only)", "tags": ["Tenants"], "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "204": { "description": "Tenant deleted" } } } }, "/tenants/slug/{slug}": { "get": { "operationId": "getTenantBySlug", "summary": "Get tenant by slug", "tags": ["Tenants"], "parameters": [{ "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Tenant details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantResponse" } } } } } } }, "/tenants/{tenantId}/activate": { "post": { "operationId": "activateTenant", "summary": "Activate a tenant (root only)", "tags": ["Tenants"], "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Tenant activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantResponse" } } } } } } }, "/tenants/{tenantId}/suspend": { "post": { "operationId": "suspendTenant", "summary": "Suspend a tenant (root only)", "tags": ["Tenants"], "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Tenant suspended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantResponse" } } } } } } }, "/tenants/{tenantId}/auth-methods": { "get": { "operationId": "getTenantMethods", "summary": "List auth methods configured for a tenant", "tags": ["Auth Methods"], "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Tenant auth methods" } } } }, "/tenants/{tenantId}/auth-methods/{authMethodId}": { "put": { "operationId": "configureTenantMethod", "summary": "Configure an auth method for a tenant", "tags": ["Auth Methods"], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "authMethodId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "enabled", "in": "query", "schema": { "type": "boolean", "default": true } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "string", "description": "Configuration JSON" } } } }, "responses": { "200": { "description": "Method configured" } } } }, "/audit-logs": { "get": { "operationId": "getAuditLogs", "summary": "Get audit logs with pagination", "tags": ["Audit"], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "size", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "userId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated audit logs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse" } } } }, "403": { "description": "Insufficient permissions" } } } }, "/audit-logs/{id}": { "get": { "operationId": "getAuditLogById", "summary": "Get audit log by ID", "tags": ["Audit"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Audit log details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogDto" } } } }, "404": { "description": "Audit log not found" } } } }, "/audit-logs/action-types": { "get": { "operationId": "getActionTypes", "summary": "Get available audit log action types", "tags": ["Audit"], "responses": { "200": { "description": "Action types list", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } } } } }, "/my/activity": { "get": { "operationId": "getMyActivity", "summary": "Get current user's own activity logs", "tags": ["Audit"], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "size", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "User activity logs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse" } } } } } } }, "/statistics": { "get": { "operationId": "getStatistics", "summary": "Get system statistics", "tags": ["System"], "responses": { "200": { "description": "System statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatisticsDto" } } } }, "403": { "description": "Requires analytics:view permission" } } } }, "/statistics/dashboard": { "get": { "operationId": "getDashboardStatistics", "summary": "Get dashboard statistics (alias for /statistics)", "tags": ["System"], "responses": { "200": { "description": "Dashboard statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatisticsDto" } } } } } } }, "/biometric/health": { "get": { "operationId": "biometricHealth", "summary": "Check biometric processor health via proxy", "tags": ["Biometric"], "responses": { "200": { "description": "Biometric processor health" }, "503": { "description": "Biometric processor unavailable" } } } }, "/biometric/enroll/{userId}": { "post": { "operationId": "enrollFace", "summary": "Enroll user's face biometric data", "tags": ["Biometric"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Enrollment result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiometricVerificationResponse" } } } } } } }, "/biometric/enroll/multi/{userId}": { "post": { "operationId": "enrollFaceMulti", "summary": "Multi-image face enrollment (2-5 images for stronger template)", "tags": ["Biometric"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "string", "format": "binary" } } } } } } }, "responses": { "200": { "description": "Multi-image enrollment result" } } } }, "/biometric/verify/{userId}": { "post": { "operationId": "verifyFace", "summary": "Verify user's face against enrolled biometric data", "tags": ["Biometric"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiometricVerificationResponse" } } } } } } }, "/biometric/fingerprint/enroll/{userId}": { "post": { "operationId": "enrollFingerprint", "summary": "Enroll user's fingerprint biometric data", "tags": ["Biometric"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fingerprintData": { "type": "string" } } } } } }, "responses": { "200": { "description": "Enrollment result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiometricVerificationResponse" } } } } } } }, "/biometric/fingerprint/verify/{userId}": { "post": { "operationId": "verifyFingerprint", "summary": "Verify user's fingerprint against enrolled biometric data", "tags": ["Biometric"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fingerprintData": { "type": "string" } } } } } }, "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiometricVerificationResponse" } } } } } } }, "/biometric/voice/enroll/{userId}": { "post": { "operationId": "enrollVoice", "summary": "Enroll user's voice biometric data", "tags": ["Biometric"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "voiceData": { "type": "string" } } } } } }, "responses": { "200": { "description": "Enrollment result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiometricVerificationResponse" } } } } } } }, "/biometric/voice/verify/{userId}": { "post": { "operationId": "verifyVoice", "summary": "Verify user's voice against enrolled biometric data", "tags": ["Biometric"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "voiceData": { "type": "string" } } } } } }, "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiometricVerificationResponse" } } } } } } }, "/biometric/face/{userId}": { "delete": { "operationId": "deleteFace", "summary": "Delete user's enrolled face biometric data", "tags": ["Biometric"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Face data deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BiometricVerificationResponse" } } } } } } }, "/biometric/fingerprint/{userId}": { "delete": { "operationId": "deleteFingerprint", "summary": "Delete user's enrolled fingerprint biometric data", "tags": ["Biometric"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Fingerprint data deleted" } } } }, "/biometric/voice/{userId}": { "delete": { "operationId": "deleteVoice", "summary": "Delete user's enrolled voice biometric data", "tags": ["Biometric"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Voice data deleted" } } } }, "/biometric/search": { "post": { "operationId": "searchFace", "summary": "Search for a face in enrolled database (1:N identification)", "tags": ["Biometric"], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "Face search results" } } } }, "/biometric/voice/search": { "post": { "operationId": "searchVoice", "summary": "Search for a speaker in enrolled database (1:N voice identification)", "tags": ["Biometric"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "voiceData": { "type": "string" } } } } } }, "responses": { "200": { "description": "Voice search results" } } } }, "/auth/biometric/devices": { "post": { "operationId": "registerAuthDevice", "summary": "Register a biometric device for step-up authentication", "tags": ["Biometric"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyId": { "type": "string" }, "platform": { "type": "string", "enum": ["WEB", "ANDROID", "IOS", "DESKTOP"] }, "publicKeyJwk": { "type": "object" } } } } } }, "responses": { "201": { "description": "Device registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceResponse" } } } } } } }, "/auth/biometric/challenge": { "post": { "operationId": "createAuthChallenge", "summary": "Request a challenge nonce for biometric verification", "tags": ["Biometric"], "responses": { "200": { "description": "Challenge created" } } } }, "/auth/biometric/verify": { "post": { "operationId": "verifyAuthSignature", "summary": "Verify a signed biometric challenge", "tags": ["Biometric"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyId": { "type": "string" }, "challengeId": { "type": "string" }, "signatureBase64": { "type": "string" } } } } } }, "responses": { "200": { "description": "Verification result" } } } }, "/roles": { "get": { "operationId": "getAllRoles", "summary": "Get all roles", "tags": ["Roles"], "parameters": [{ "name": "includeInactive", "in": "query", "schema": { "type": "boolean", "default": false } }], "responses": { "200": { "description": "Roles list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoleResponse" } } } } } } }, "post": { "operationId": "createRole", "summary": "Create new role", "tags": ["Roles"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoleRequest" } } } }, "responses": { "201": { "description": "Role created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleResponse" } } } } } } }, "/roles/{id}": { "get": { "operationId": "getRoleById", "summary": "Get role by ID", "tags": ["Roles"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Role details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleResponse" } } } } } }, "put": { "operationId": "updateRole", "summary": "Update role", "tags": ["Roles"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleRequest" } } } }, "responses": { "200": { "description": "Role updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleResponse" } } } } } }, "delete": { "operationId": "deleteRole", "summary": "Delete role (soft delete)", "tags": ["Roles"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "204": { "description": "Role deleted" } } } }, "/roles/tenant/{tenantId}": { "get": { "operationId": "getRolesByTenant", "summary": "Get roles by tenant", "tags": ["Roles"], "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Tenant roles", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RoleResponse" } } } } } } } }, "/roles/{roleId}/permissions/{permissionId}": { "post": { "operationId": "assignPermission", "summary": "Assign permission to role", "tags": ["Roles"], "parameters": [ { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "permissionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Permission assigned" } } }, "delete": { "operationId": "revokePermission", "summary": "Revoke permission from role", "tags": ["Roles"], "parameters": [ { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "permissionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Permission revoked" } } } }, "/users/{userId}/roles": { "get": { "operationId": "getUserRoles", "summary": "Get all roles for a user", "tags": ["Roles"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "User roles" } } } }, "/users/{userId}/roles/{roleId}": { "post": { "operationId": "assignRole", "summary": "Assign a role to a user", "tags": ["Roles"], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "responses": { "201": { "description": "Role assigned" } } }, "delete": { "operationId": "revokeRole", "summary": "Revoke a role from a user", "tags": ["Roles"], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "roleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Role revoked" } } } }, "/permissions": { "get": { "operationId": "getAllPermissions", "summary": "Get all permissions", "tags": ["Roles"], "responses": { "200": { "description": "Permissions list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionResponse" } } } } } } } }, "/permissions/{id}": { "get": { "operationId": "getPermissionById", "summary": "Get permission by ID", "tags": ["Roles"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Permission details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionResponse" } } } } } } }, "/permissions/resource/{resource}": { "get": { "operationId": "getPermissionsByResource", "summary": "Get permissions by resource", "tags": ["Roles"], "parameters": [{ "name": "resource", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Resource permissions" } } } }, "/otp/email/send/{userId}": { "post": { "operationId": "sendEmailOtp", "summary": "Send an OTP code via email to the user", "tags": ["OTP"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OTP sent" } } } }, "/otp/email/verify/{userId}": { "post": { "operationId": "verifyEmailOtp", "summary": "Verify an email OTP code", "tags": ["OTP"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "OTP verification result" } } } }, "/otp/sms/send/{userId}": { "post": { "operationId": "sendSmsOtp", "summary": "Send an OTP code via SMS to the user", "tags": ["OTP"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "OTP sent" }, "400": { "description": "No phone number configured" } } } }, "/otp/sms/verify/{userId}": { "post": { "operationId": "verifySmsOtp", "summary": "Verify an SMS OTP code", "tags": ["OTP"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "OTP verification result" } } } }, "/totp/setup/{userId}": { "post": { "operationId": "setupTotp", "summary": "Set up TOTP for a user - generates secret and OTP auth URI", "tags": ["OTP"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "TOTP setup info", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" }, "otpAuthUri": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "/totp/verify-setup/{userId}": { "post": { "operationId": "verifyTotpSetup", "summary": "Verify TOTP setup by providing an initial code from authenticator app", "tags": ["OTP"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "TOTP setup verification result" } } } }, "/totp/status/{userId}": { "get": { "operationId": "getTotpStatus", "summary": "Check if TOTP is configured for a user", "tags": ["OTP"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "TOTP status", "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "configured": { "type": "boolean" } } } } } } } } }, "/totp/{userId}": { "delete": { "operationId": "revokeTotp", "summary": "Revoke/disable TOTP for a user", "tags": ["OTP"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "TOTP disabled" } } } }, "/qr/generate/{userId}": { "post": { "operationId": "generateQrToken", "summary": "Generate a QR authentication token for the user", "tags": ["QR Authentication"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "QR token generated" } } } }, "/qr/{token}": { "delete": { "operationId": "invalidateQrToken", "summary": "Invalidate a QR authentication token", "tags": ["QR Authentication"], "parameters": [{ "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "204": { "description": "Token invalidated" } } } }, "/auth/qr/session": { "post": { "operationId": "createQrSession", "summary": "Create a new QR login session", "tags": ["QR Authentication"], "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string" } } } } } }, "responses": { "200": { "description": "QR session created" } } } }, "/auth/qr/session/{sessionId}": { "get": { "operationId": "getQrSession", "summary": "Get QR login session status (poll endpoint)", "tags": ["QR Authentication"], "security": [], "parameters": [{ "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Session status" } } } }, "/auth/qr/session/{sessionId}/approve": { "post": { "operationId": "approveQrSession", "summary": "Approve a QR login session (from authenticated mobile user)", "tags": ["QR Authentication"], "parameters": [{ "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Session approved" } } } }, "/nfc/enroll": { "post": { "operationId": "enrollNfcCard", "summary": "Enroll an NFC card for a user", "tags": ["NFC"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["cardSerial"], "properties": { "userId": { "type": "string" }, "cardSerial": { "type": "string" }, "cardType": { "type": "string" }, "label": { "type": "string" } } } } } }, "responses": { "201": { "description": "Card enrolled" }, "409": { "description": "Card already enrolled in tenant" } } } }, "/nfc/verify": { "post": { "operationId": "verifyNfcCard", "summary": "Verify an NFC card - returns user info if enrolled", "tags": ["NFC"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["cardSerial"], "properties": { "cardSerial": { "type": "string" } } } } } }, "responses": { "200": { "description": "Card verification result" } } } }, "/nfc/search/{serial}": { "get": { "operationId": "searchNfcCard", "summary": "Look up who owns a specific NFC card serial", "tags": ["NFC"], "parameters": [{ "name": "serial", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Card search result" } } } }, "/nfc/{userId}": { "delete": { "operationId": "removeNfcEnrollment", "summary": "Remove NFC enrollment for a user", "tags": ["NFC"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "NFC enrollment removed" } } } }, "/nfc/user/{userId}": { "get": { "operationId": "listNfcUserCards", "summary": "List all NFC cards for a user", "tags": ["NFC"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "User NFC cards" } } } }, "/devices": { "get": { "operationId": "getDevices", "summary": "List devices", "tags": ["Devices"], "parameters": [ { "name": "userId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenantId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Devices list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceResponse" } } } } } } }, "post": { "operationId": "registerDevice", "summary": "Register a new device", "tags": ["Devices"], "parameters": [ { "name": "userId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tenantId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterDeviceCommand" } } } }, "responses": { "201": { "description": "Device registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceResponse" } } } } } } }, "/devices/{deviceId}": { "delete": { "operationId": "removeDevice", "summary": "Remove a device", "tags": ["Devices"], "parameters": [{ "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "204": { "description": "Device removed" } } } }, "/webauthn/register/options/{userId}": { "post": { "operationId": "getWebAuthnRegistrationOptions", "summary": "Generate WebAuthn registration options (challenge) for credential creation", "tags": ["WebAuthn"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Registration options with challenge" } } } }, "/webauthn/register/verify": { "post": { "operationId": "verifyWebAuthnRegistration", "summary": "Verify WebAuthn registration (attestation) and store credential", "tags": ["WebAuthn"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string" }, "sessionId": { "type": "string" }, "credentialId": { "type": "string" }, "publicKey": { "type": "string" }, "publicKeyAlgorithm": { "type": "string" }, "attestationFormat": { "type": "string" }, "transports": { "type": "string" }, "deviceName": { "type": "string" }, "clientDataJSON": { "type": "string" } } } } } }, "responses": { "201": { "description": "Credential registered" }, "400": { "description": "Invalid challenge or missing data" }, "409": { "description": "Credential already registered" } } } }, "/webauthn/credentials/{userId}": { "get": { "operationId": "listWebAuthnCredentials", "summary": "List all WebAuthn credentials for a user", "tags": ["WebAuthn"], "parameters": [{ "name": "userId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "200": { "description": "Credentials list" } } } }, "/webauthn/credentials/by-id/{id}": { "delete": { "operationId": "deleteWebAuthnCredentialById", "summary": "Delete a WebAuthn credential by database ID", "tags": ["WebAuthn"], "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }], "responses": { "204": { "description": "Credential deleted" }, "404": { "description": "Credential not found" } } } }, "/webauthn/credentials/{credentialId}": { "delete": { "operationId": "deleteWebAuthnCredential", "summary": "Delete a WebAuthn credential by credential ID", "tags": ["WebAuthn"], "parameters": [{ "name": "credentialId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "204": { "description": "Credential deleted" }, "404": { "description": "Credential not found" } } } }, "/webauthn/register-options": { "post": { "operationId": "webAuthnRegisterOptions", "summary": "Generate WebAuthn registration options for the currently authenticated user", "tags": ["WebAuthn"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceName": { "type": "string" } } } } } }, "responses": { "200": { "description": "Registration options" } } } }, "/webauthn/register": { "post": { "operationId": "webAuthnRegister", "summary": "Complete WebAuthn registration: validate attestation and store credential", "tags": ["WebAuthn"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "credentialId": { "type": "string" }, "publicKey": { "type": "string" }, "publicKeyAlgorithm": { "type": "string" }, "attestationFormat": { "type": "string" }, "transports": { "type": "string" }, "deviceName": { "type": "string" }, "clientDataJSON": { "type": "string" } } } } } }, "responses": { "201": { "description": "Credential registered" } } } }, "/webauthn/authenticate-options": { "post": { "operationId": "webAuthnAuthenticateOptions", "summary": "Generate WebAuthn authentication options (challenge) for navigator.credentials.get()", "tags": ["WebAuthn"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string" } } } } } }, "responses": { "200": { "description": "Authentication options with challenge and allowed credentials" }, "400": { "description": "No credentials available" } } } }, "/webauthn/authenticate": { "post": { "operationId": "webAuthnAuthenticate", "summary": "Verify WebAuthn authentication assertion from navigator.credentials.get()", "tags": ["WebAuthn"], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["sessionId", "credentialId", "authenticatorData", "clientDataJSON", "signature"], "properties": { "sessionId": { "type": "string" }, "credentialId": { "type": "string" }, "authenticatorData": { "type": "string" }, "clientDataJSON": { "type": "string" }, "signature": { "type": "string" } } } } } }, "responses": { "200": { "description": "Authentication successful" }, "401": { "description": "Authentication failed" } } } }, "/step-up/register-device": { "post": { "operationId": "registerStepUpDevice", "summary": "Register device public key for step-up auth", "tags": ["Devices"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Device registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceResponse" } } } } } } }, "/step-up/challenge": { "post": { "operationId": "requestStepUpChallenge", "summary": "Request a challenge nonce for step-up verification", "tags": ["Devices"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Challenge created" } } } }, "/step-up/verify-challenge": { "post": { "operationId": "verifyStepUpChallenge", "summary": "Verify signed challenge for step-up authentication", "tags": ["Devices"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "keyId": { "type": "string" }, "challengeId": { "type": "string" }, "signatureBase64": { "type": "string" } } } } } }, "responses": { "200": { "description": "Step-up verification result" } } } }, "/auth-methods": { "get": { "operationId": "getAllAuthMethods", "summary": "List all auth methods", "tags": ["Auth Methods"], "security": [], "responses": { "200": { "description": "Auth methods list" } } } }, "/auth-methods/{type}": { "get": { "operationId": "getAuthMethodByType", "summary": "Get auth method by type", "tags": ["Auth Methods"], "security": [], "parameters": [{ "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": ["PASSWORD", "EMAIL_OTP", "SMS_OTP", "TOTP", "FACE", "VOICE", "FINGERPRINT", "HARDWARE_KEY", "QR_CODE", "NFC_DOCUMENT"] } }], "responses": { "200": { "description": "Auth method details" } } } }, "/auth-flows": { "get": { "operationId": "getAllAuthFlowsAdmin", "summary": "List all auth flows across all tenants (admin)", "tags": ["Admin Overview"], "parameters": [{ "name": "operationType", "in": "query", "required": false, "schema": { "type": "string" } }], "responses": { "200": { "description": "All auth flows" } } } }, "/auth-sessions": { "get": { "operationId": "getAllAuthSessionsAdmin", "summary": "List all auth sessions across all tenants (admin)", "tags": ["Admin Overview"], "responses": { "200": { "description": "All auth sessions" } } } }, "/.well-known/openid-configuration": { "get": { "operationId": "openidConfiguration", "summary": "OpenID Connect discovery document", "description": "Returns OIDC provider metadata (issuer, endpoints, supported scopes, claims, PKCE methods). Note: This endpoint is at the server root, not under /api/v1.", "tags": ["OpenID Connect"], "security": [], "servers": [{ "url": "https://api.fivucsas.com" }], "responses": { "200": { "description": "OIDC discovery document", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/jwks.json": { "get": { "operationId": "jwks", "summary": "JSON Web Key Set for token verification metadata", "description": "Returns JWKS metadata. Since this service uses HMAC-SHA512 (symmetric key), the actual secret is never exposed. Note: This endpoint is at the server root, not under /api/v1.", "tags": ["OpenID Connect"], "security": [], "servers": [{ "url": "https://api.fivucsas.com" }], "responses": { "200": { "description": "JWKS document", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object" } } } } } } } } } } } }