{ "openapi": "3.0.0", "paths": { "/api/v1": { "get": { "description": "Returns the public service identity when the API process is available.", "operationId": "getServiceStatus", "parameters": [], "responses": { "200": { "description": "The API process is available.", "content": { "application/json": { "schema": { "type": "string" }, "example": "CUP CS API is running" } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Get service status", "tags": ["System"] } }, "/api/v1/health/live": { "get": { "description": "Returns success when the API process can handle requests. It does not expose dependency details.", "operationId": "getLiveness", "parameters": [], "responses": { "200": { "description": "The process is running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponseDto" }, "example": { "status": "ok" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Check process liveness", "tags": ["System"] } }, "/api/v1/health/ready": { "get": { "description": "Checks critical dependencies and returns only a safe readiness result.", "operationId": "getReadiness", "parameters": [], "responses": { "200": { "description": "Critical dependencies are available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponseDto" }, "example": { "status": "ok" } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "503": { "description": "A critical dependency is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "HTTP.503", "message": "The service is temporarily unavailable", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Check service readiness", "tags": ["System"] } }, "/api/v1/auth/invitations/accept": { "post": { "description": "Validates the single-use invitation token, invited email, and frontend-generated temporary password before issuing a restricted activation token.", "operationId": "acceptUserInvitation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInvitationDto" }, "example": { "email": "user@example.com", "temporaryPassword": "Example#Password123", "token": "safe-placeholder" } } } }, "responses": { "201": { "description": "Invitation accepted and restricted activation token issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestrictedTokenResponseDto" }, "example": { "restrictedToken": "restricted-token-example" } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "VALIDATION.FAILED", "message": "The submitted data is invalid", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "401": { "description": "Invitation or temporary credential is invalid or no longer eligible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "HTTP.401", "message": "Authentication is required", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Validate an invitation and temporary credential", "tags": ["Authentication"] } }, "/api/v1/auth/activation/totp/enroll": { "post": { "description": "Generates an encrypted TOTP credential and returns the enrollment URI only to a caller holding the correct activation-purpose token.", "operationId": "enrollActivationTotp", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestrictedTokenDto" }, "example": { "restrictedToken": "restricted-token-example" } } } }, "responses": { "201": { "description": "TOTP enrollment created for the restricted activation flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpEnrollmentResponseDto" }, "example": { "restrictedToken": "restricted-token-example", "enrollmentUri": "otpauth://totp/CUP:user@example.com?secret=EXAMPLEONLY" } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "VALIDATION.FAILED", "message": "The submitted data is invalid", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Create restricted TOTP enrollment", "tags": ["Authentication"] } }, "/api/v1/auth/activation/totp/verify": { "post": { "description": "Verifies the first authenticator code and advances the purpose-bound activation token to permanent-password replacement.", "operationId": "verifyActivationTotp", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyTotpDto" }, "example": { "restrictedToken": "restricted-token-example", "token": "safe-placeholder" } } } }, "responses": { "201": { "description": "TOTP enrollment verified and activation token advanced.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestrictedTokenResponseDto" }, "example": { "restrictedToken": "restricted-token-example" } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "VALIDATION.FAILED", "message": "The submitted data is invalid", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Verify the first TOTP code", "tags": ["Authentication"] } }, "/api/v1/auth/activation/complete": { "post": { "description": "Replaces the invitation credential with a different policy-compliant password, activates the account, consumes the invitation, and creates the first persisted session.", "operationId": "completeUserActivation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteActivationDto" }, "example": { "newPassword": "Example#Password123", "restrictedToken": "restricted-token-example" } } } }, "responses": { "201": { "description": "Account activated and first authenticated session created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponseDto" }, "example": { "accessToken": "eyJhbGciOiJIUzI1NiJ9.example.signature", "expiresAt": "2026-01-01T00:00:00.000Z", "sessionId": "00000000-0000-4000-8000-000000000000", "profile": { "id": "00000000-0000-4000-8000-000000000000", "email": "user@example.com", "fullName": "Example User", "locale": "ar", "userType": "SUPER_ADMIN", "tenantId": "00000000-0000-4000-8000-000000000000", "permissions": [ { "feature": "USERS", "actions": [ { "id": "00000000-0000-4000-8000-000000000000", "code": "READ" } ] } ] } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "VALIDATION.FAILED", "message": "The submitted data is invalid", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Replace the temporary password and activate the account", "tags": ["Authentication"] } }, "/api/v1/auth/mfa/re-enrollment/complete": { "post": { "description": "Completes mandatory MFA re-enrollment after an administrative reset and creates a new persisted session only after valid TOTP proof.", "operationId": "completeMfaReenrollment", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyTotpDto" }, "example": { "restrictedToken": "restricted-token-example", "token": "safe-placeholder" } } } }, "responses": { "201": { "description": "Replacement MFA factor verified and session created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponseDto" }, "example": { "accessToken": "eyJhbGciOiJIUzI1NiJ9.example.signature", "expiresAt": "2026-01-01T00:00:00.000Z", "sessionId": "00000000-0000-4000-8000-000000000000", "profile": { "id": "00000000-0000-4000-8000-000000000000", "email": "user@example.com", "fullName": "Example User", "locale": "ar", "userType": "SUPER_ADMIN", "tenantId": "00000000-0000-4000-8000-000000000000", "permissions": [ { "feature": "USERS", "actions": [ { "id": "00000000-0000-4000-8000-000000000000", "code": "READ" } ] } ] } } } } }, "400": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "VALIDATION.FAILED", "message": "The submitted data is invalid", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Verify a replacement TOTP factor and create a session", "tags": ["Authentication"] } }, "/api/v1/auth/platform/sign-in": { "post": { "description": "Verifies the password and current platform eligibility, then issues a restricted TOTP challenge without creating a session. An on-leave Operator is informed that successful continuation makes the account available.", "operationId": "signInPlatformUser", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInDto" }, "example": { "email": "user@example.com", "password": "Example#Password123" } } } }, "responses": { "200": { "description": "Password accepted and a restricted TOTP or MFA re-enrollment step is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInResponseDto" }, "example": { "nextStep": "MFA_REENROLLMENT_REQUIRED", "restrictedToken": "restricted-token-example", "expiresAt": "2026-01-01T00:00:00.000Z", "enrollmentUri": "otpauth://totp/CUP:user@example.com?secret=EXAMPLEONLY", "operatorWillBecomeAvailable": true } } } }, "400": { "description": "Email/password request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "VALIDATION.FAILED", "message": "The submitted data is invalid", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "401": { "description": "Credentials are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "HTTP.401", "message": "Authentication is required", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "403": { "description": "Account or current platform eligibility is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "AUTH.PERMISSION_DENIED", "message": "You do not have permission to perform this action.", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "423": { "description": "The account is temporarily locked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "GE-LOCK-423", "message": "The account has been temporarily locked.", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Sign in a Super Administrator or Operator", "tags": ["Authentication"] } }, "/api/v1/auth/platform/sign-in/totp": { "post": { "description": "Consumes the matching password challenge and verifies current TOTP before creating the authenticated platform session.", "operationId": "completePlatformUserSignIn", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteSignInDto" }, "example": { "restrictedToken": "restricted-token-example", "totpToken": "safe-placeholder" } } } }, "responses": { "200": { "description": "TOTP accepted and authenticated session created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponseDto" }, "example": { "accessToken": "eyJhbGciOiJIUzI1NiJ9.example.signature", "expiresAt": "2026-01-01T00:00:00.000Z", "sessionId": "00000000-0000-4000-8000-000000000000", "profile": { "id": "00000000-0000-4000-8000-000000000000", "email": "user@example.com", "fullName": "Example User", "locale": "ar", "userType": "SUPER_ADMIN", "tenantId": "00000000-0000-4000-8000-000000000000", "permissions": [ { "feature": "USERS", "actions": [ { "id": "00000000-0000-4000-8000-000000000000", "code": "READ" } ] } ] } } } } }, "400": { "description": "Restricted token or TOTP request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "VALIDATION.FAILED", "message": "The submitted data is invalid", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "401": { "description": "The TOTP is invalid or the challenge is expired, stale, replayed, altered, or for another audience/purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "HTTP.401", "message": "Authentication is required", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "403": { "description": "Account or current platform eligibility is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "AUTH.PERMISSION_DENIED", "message": "You do not have permission to perform this action.", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "423": { "description": "The account is temporarily locked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "GE-LOCK-423", "message": "The account has been temporarily locked.", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Complete platform sign-in with TOTP", "tags": ["Authentication"] } }, "/api/v1/auth/tenant/sign-in": { "post": { "description": "Verifies the password and current user, tenant, subscription, lockout, and source-IP eligibility, then issues a restricted TOTP challenge without creating a session.", "operationId": "signInTenantUser", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInDto" }, "example": { "email": "user@example.com", "password": "Example#Password123" } } } }, "responses": { "200": { "description": "Password accepted and a restricted second step is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignInResponseDto" }, "example": { "nextStep": "MFA_REENROLLMENT_REQUIRED", "restrictedToken": "restricted-token-example", "expiresAt": "2026-01-01T00:00:00.000Z", "enrollmentUri": "otpauth://totp/CUP:user@example.com?secret=EXAMPLEONLY", "operatorWillBecomeAvailable": true } } } }, "400": { "description": "Email/password request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "VALIDATION.FAILED", "message": "The submitted data is invalid", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "401": { "description": "Credentials are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "HTTP.401", "message": "Authentication is required", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "403": { "description": "Account, tenant, subscription, or source-IP eligibility is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "AUTH.PERMISSION_DENIED", "message": "You do not have permission to perform this action.", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "423": { "description": "The account is temporarily locked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "GE-LOCK-423", "message": "The account has been temporarily locked.", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Sign in a tenant administrator or tenant user", "tags": ["Authentication"] } }, "/api/v1/auth/tenant/sign-in/totp": { "post": { "description": "Consumes the matching password challenge and verifies current TOTP while rechecking tenant, subscription, and source-IP eligibility before creating the session.", "operationId": "completeTenantUserSignIn", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteSignInDto" }, "example": { "restrictedToken": "restricted-token-example", "totpToken": "safe-placeholder" } } } }, "responses": { "200": { "description": "TOTP accepted and authenticated session created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponseDto" }, "example": { "accessToken": "eyJhbGciOiJIUzI1NiJ9.example.signature", "expiresAt": "2026-01-01T00:00:00.000Z", "sessionId": "00000000-0000-4000-8000-000000000000", "profile": { "id": "00000000-0000-4000-8000-000000000000", "email": "user@example.com", "fullName": "Example User", "locale": "ar", "userType": "SUPER_ADMIN", "tenantId": "00000000-0000-4000-8000-000000000000", "permissions": [ { "feature": "USERS", "actions": [ { "id": "00000000-0000-4000-8000-000000000000", "code": "READ" } ] } ] } } } } }, "400": { "description": "Restricted token or TOTP request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "VALIDATION.FAILED", "message": "The submitted data is invalid", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "401": { "description": "The TOTP is invalid or the challenge is expired, stale, replayed, altered, or for another audience/purpose.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "HTTP.401", "message": "Authentication is required", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "403": { "description": "Account, tenant, subscription, or source-IP eligibility is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "AUTH.PERMISSION_DENIED", "message": "You do not have permission to perform this action.", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "423": { "description": "The account is temporarily locked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "GE-LOCK-423", "message": "The account has been temporarily locked.", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Complete tenant sign-in with TOTP", "tags": ["Authentication"] } }, "/api/v1/auth/refresh": { "post": { "description": "Validates Origin and double-submit CSRF, atomically spends the current opaque refresh token, and rotates it within the persisted session family.", "operationId": "refreshUserSession", "parameters": [], "responses": { "200": { "description": "Refresh token rotated and fresh access token issued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponseDto" }, "example": { "accessToken": "eyJhbGciOiJIUzI1NiJ9.example.signature", "expiresAt": "2026-01-01T00:00:00.000Z", "sessionId": "00000000-0000-4000-8000-000000000000", "profile": { "id": "00000000-0000-4000-8000-000000000000", "email": "user@example.com", "fullName": "Example User", "locale": "ar", "userType": "SUPER_ADMIN", "tenantId": "00000000-0000-4000-8000-000000000000", "permissions": [ { "feature": "USERS", "actions": [ { "id": "00000000-0000-4000-8000-000000000000", "code": "READ" } ] } ] } } } } }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Rotate the refresh token and issue a new access token", "tags": ["Authentication"] } }, "/api/v1/auth/sign-out": { "post": { "description": "Validates cookie-request CSRF when a refresh cookie is present, terminates the associated persisted session, and clears authentication cookies.", "operationId": "signOutUserSession", "parameters": [], "responses": { "204": { "description": "Session is terminated or was already absent, and cookies are cleared." }, "500": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseDto" }, "examples": { "standardError": { "value": { "error": { "code": "INTERNAL.UNEXPECTED", "message": "An unexpected server error occurred", "details": [], "traceId": "00000000-0000-4000-8000-000000000000" } } } } } } } }, "summary": "Idempotently terminate the current session", "tags": ["Authentication"] } } }, "info": { "title": "CYBERA Unified Platform API — Public", "description": "Public CUP API contract. Internal and administrative operations are excluded by a reviewed default-deny policy.", "version": "1.0.0", "contact": {} }, "tags": [ { "name": "System", "description": "Service availability and dependency health." }, { "name": "Authentication", "description": "Sign-in, password bootstrap, token rotation, and session revocation." } ], "servers": [ { "url": "/", "description": "Current environment" } ], "components": { "schemas": { "CompleteSignInDto": { "type": "object", "properties": { "restrictedToken": { "type": "string", "description": "Short-lived, purpose-bound challenge returned by the matching password sign-in operation.", "writeOnly": true }, "totpToken": { "type": "string", "description": "Current six-digit authenticator code.", "pattern": "^\\d{6}$", "writeOnly": true } }, "required": ["restrictedToken", "totpToken"] }, "SignInResponseDto": { "type": "object", "properties": { "nextStep": { "type": "string", "description": "The required second authentication step. No authenticated session exists yet.", "enum": ["MFA_REENROLLMENT_REQUIRED", "TOTP_REQUIRED"] }, "restrictedToken": { "type": "string", "description": "Short-lived purpose-bound token accepted only by the indicated next step.", "readOnly": true, "example": "restricted-token-example" }, "expiresAt": { "type": "string", "description": "UTC expiry of the restricted next-step token.", "format": "date-time" }, "enrollmentUri": { "type": "string", "description": "TOTP enrollment URI returned only when administrative MFA reset requires re-enrollment.", "readOnly": true, "example": "otpauth://totp/CUP:user@example.com?secret=EXAMPLEONLY" }, "operatorWillBecomeAvailable": { "type": "boolean", "description": "True when successful continuation will change an Operator from on-leave to available.", "example": true } }, "required": ["nextStep", "restrictedToken"] }, "SignInDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Normalized login email for the selected authentication audience.", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "description": "Account password, accepted only over the protected transport.", "writeOnly": true } }, "required": ["email", "password"] }, "AuthSessionResponseDto": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Short-lived bearer access token bound to the persisted user session.", "readOnly": true, "example": "eyJhbGciOiJIUzI1NiJ9.example.signature" }, "expiresAt": { "type": "string", "description": "UTC expiry of the access token and returned session view.", "format": "date-time" }, "sessionId": { "type": "string", "description": "Identifier of the persisted, immediately revocable user session.", "format": "uuid" }, "profile": { "description": "Authenticated identity and live permissions for the issued token context.", "allOf": [ { "$ref": "#/components/schemas/AuthenticatedUserProfileDto" } ] } }, "required": ["accessToken", "expiresAt", "sessionId", "profile"] }, "AuthenticatedUserProfileDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Authenticated user identifier.", "format": "uuid" }, "email": { "type": "string", "description": "Authenticated user email address.", "format": "email", "example": "user@example.com" }, "fullName": { "type": "string", "description": "Authenticated user display name.", "example": "Example User" }, "locale": { "type": "string", "description": "Preferred interface locale.", "enum": ["ar", "en"] }, "userType": { "type": "string", "description": "Account type that determines the authenticated audience.", "enum": ["SUPER_ADMIN", "OPERATOR", "TENANT_ADMIN", "TENANT_USER"] }, "tenantId": { "type": "string", "description": "Owning tenant identifier. Present only for tenant administrators and tenant users.", "format": "uuid" }, "permissions": { "description": "Live effective permissions for the current platform or tenant context.", "type": "array", "items": { "$ref": "#/components/schemas/EffectivePermissionGroupDto" } } }, "required": [ "id", "email", "fullName", "locale", "userType", "permissions" ] }, "EffectivePermissionGroupDto": { "type": "object", "properties": { "feature": { "type": "string", "description": "Feature or permission-module code.", "example": "USERS" }, "actions": { "description": "Actions currently effective within this feature.", "type": "array", "items": { "$ref": "#/components/schemas/EffectivePermissionActionDto" } } }, "required": ["feature", "actions"] }, "EffectivePermissionActionDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable identifier of the effective permission.", "format": "uuid" }, "code": { "type": "string", "description": "Action code evaluated by server-side authorization.", "example": "READ" } }, "required": ["id", "code"] }, "CompleteActivationDto": { "type": "object", "properties": { "newPassword": { "type": "string", "description": "Permanent complex password replacing the temporary invitation credential.", "minLength": 12, "maxLength": 32, "writeOnly": true }, "restrictedToken": { "type": "string", "description": "Purpose-bound token proving invitation acceptance and verified TOTP enrollment.", "writeOnly": true } }, "required": ["newPassword", "restrictedToken"] }, "VerifyTotpDto": { "type": "object", "properties": { "restrictedToken": { "type": "string", "description": "Short-lived purpose-bound enrollment or re-enrollment token.", "writeOnly": true }, "token": { "type": "string", "description": "Current six-digit code from the enrolled authenticator.", "pattern": "^\\d{6}$", "writeOnly": true } }, "required": ["restrictedToken", "token"] }, "TotpEnrollmentResponseDto": { "type": "object", "properties": { "restrictedToken": { "type": "string", "description": "Short-lived purpose-bound token used only by the next restricted activation step.", "readOnly": true, "example": "restricted-token-example" }, "enrollmentUri": { "type": "string", "description": "One-time authenticator enrollment URI. It is returned only in the restricted activation flow.", "readOnly": true, "example": "otpauth://totp/CUP:user@example.com?secret=EXAMPLEONLY" } }, "required": ["restrictedToken", "enrollmentUri"] }, "RestrictedTokenDto": { "type": "object", "properties": { "restrictedToken": { "type": "string", "description": "Short-lived purpose-bound token issued by the prior flow step.", "writeOnly": true } }, "required": ["restrictedToken"] }, "RestrictedTokenResponseDto": { "type": "object", "properties": { "restrictedToken": { "type": "string", "description": "Short-lived purpose-bound token used only by the next restricted activation step.", "readOnly": true, "example": "restricted-token-example" } }, "required": ["restrictedToken"] }, "AcceptInvitationDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address bound to the pending invitation.", "format": "email", "example": "user@example.com" }, "temporaryPassword": { "type": "string", "description": "Frontend-generated temporary password supplied when the user was invited.", "writeOnly": true, "minLength": 8, "maxLength": 32 }, "token": { "type": "string", "description": "Single-use invitation token received through the fixed mail link.", "writeOnly": true } }, "required": ["email", "temporaryPassword", "token"] }, "HealthResponseDto": { "type": "object", "properties": { "status": { "type": "string", "description": "Safe service health state.", "enum": ["ok"], "example": "ok" } }, "required": ["status"] }, "ErrorResponseDto": { "type": "object", "properties": { "error": { "description": "Standard CUP error envelope.", "allOf": [ { "$ref": "#/components/schemas/ErrorBodyDto" } ] } }, "required": ["error"] }, "ErrorBodyDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable application error code.", "example": "GE-AUTH-401" }, "message": { "type": "string", "description": "Safe message localized using the request language.", "example": "Authentication failed." }, "details": { "description": "Safe field-level or contextual details.", "type": "array", "items": { "$ref": "#/components/schemas/ErrorDetailDto" } }, "traceId": { "type": "string", "description": "Trace identifier for support and sanitized log correlation.", "example": "01J8YJ3M8R8Q1M2C3D4E5F6G7H" } }, "required": ["code", "message", "details", "traceId"] }, "ErrorDetailDto": { "type": "object", "properties": { "field": { "type": "string", "description": "Request field associated with the error, when safe to expose.", "example": "email" }, "code": { "type": "string", "description": "Stable machine-readable detail code.", "example": "VALIDATION.INVALID_EMAIL" }, "message": { "type": "string", "description": "Localized safe detail message.", "example": "Email must be a valid address." } }, "required": ["code", "message"] } }, "securitySchemes": {} }, "externalDocs": { "description": "CUP developer documentation", "url": "/documentation/" } }