RegisterRequest:
type: object
description: Request body for POST /auth/register
properties:
username:
type: string
description: Desired username
example: "newuser"
email:
type: string
format: email
description: Email address for the new account
example: "newuser@example.com"
password:
type: string
format: password
description: Password that satisfies the server's validation rules
example: "SecurePassword123!"
required:
- username
- email
- password
RegisterResponse:
type: object
description: Successful registration payload returned in ApiResponse.data
properties:
user_id:
type: string
description: System-generated user identifier
example: "user_123456"
username:
type: string
example: "newuser"
email:
type: string
format: email
example: "newuser@example.com"
required:
- user_id
- username
- email
LoginRequest:
type: object
description: Request body for POST /auth/login
properties:
username:
type: string
description: Username supplied by the caller
example: "user@example.com"
password:
type: string
format: password
description: User password
example: "SecurePassword123!"
challenge_id:
type: string
nullable: true
description: Pending MFA challenge identifier returned by a previous login attempt
mfa_code:
type: string
nullable: true
description: TOTP or backup code used to satisfy a pending MFA challenge
remember_me:
type: boolean
description: Whether to request an extended session lifetime
default: false
required:
- username
- password
LoginResponse:
type: object
description: Successful login payload returned in ApiResponse.data
properties:
access_token:
type: string
description: JWT access token
example: "eyJhbGciOi..."
refresh_token:
type: string
description: JWT refresh token
example: "eyJhbGciOi..."
token_type:
type: string
description: Always Bearer
example: "Bearer"
expires_in:
type: integer
description: Access token lifetime in seconds
example: 3600
user:
$ref: "#/UserInfo"
login_risk_level:
type: string
enum: [low, medium, high, critical]
description: Header-based risk classification assigned to the login attempt
security_warnings:
type: array
items:
type: string
description: Non-blocking warnings for elevated-risk sessions
required:
- access_token
- refresh_token
- token_type
- expires_in
- user
- login_risk_level
- security_warnings
RefreshTokenRequest:
type: object
description: Request body for POST /auth/refresh
properties:
refresh_token:
type: string
description: Refresh token issued during a previous login
example: "eyJhbGciOi..."
required:
- refresh_token
TokenResponse:
type: object
description: Access-token refresh payload returned in ApiResponse.data
properties:
access_token:
type: string
description: Newly issued access token
example: "eyJhbGciOi..."
token_type:
type: string
description: Always Bearer
example: "Bearer"
expires_in:
type: integer
description: Access token lifetime in seconds
example: 3600
required:
- access_token
- token_type
- expires_in
LogoutRequest:
type: object
description: Request body for POST /auth/logout
properties:
refresh_token:
type: string
nullable: true
description: Optional refresh token to revoke alongside the bearer token
UserInfo:
type: object
description: Identity payload returned by /auth/login and /auth/validate
properties:
id:
type: string
description: Unique user identifier
example: "user_123"
username:
type: string
description: Username associated with the token
example: "user@example.com"
roles:
type: array
items:
type: string
description: Effective role names
example: ["user"]
permissions:
type: array
items:
type: string
description: Effective permissions
example: ["profile:read", "profile:write"]
required:
- id
- username
- roles
- permissions
TokenValidationResponse:
allOf:
- $ref: "#/UserInfo"