MATIH Platform is in active MVP development. Documentation reflects current implementation status.
6. Identity & Access Management
API Reference
Auth Endpoints

Auth Endpoints

The authentication endpoints handle user login, registration, email verification, token refresh, and logout. These are the only IAM endpoints that do not require a Bearer token. All endpoints are served by AuthController at /api/v1/auth.

Endpoints

MethodEndpointDescription
POST/api/v1/auth/loginAuthenticate with email and password
POST/api/v1/auth/mfa/verifyComplete MFA challenge after login
POST/api/v1/auth/registerCreate a new user account
POST/api/v1/auth/verify-emailVerify email with code
POST/api/v1/auth/resend-verificationResend verification email
POST/api/v1/auth/refreshObtain new access token via refresh token
POST/api/v1/auth/logoutRevoke refresh token

POST /api/v1/auth/login

Authenticates a user with email and password. If MFA is enabled, returns an MfaChallengeResponse instead of tokens.

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Responses:

StatusDescription
200AuthResponse with tokens, or MfaChallengeResponse if MFA is required
401Invalid credentials
423Account locked after too many failed attempts

POST /api/v1/auth/mfa/verify

Completes the login flow by verifying an MFA code (TOTP, SMS, or backup code).

{
  "challengeId": "uuid-challenge-id",
  "code": "123456"
}
StatusDescription
200AuthResponse with access and refresh tokens
400Invalid or expired challenge
401Invalid verification code

POST /api/v1/auth/register

Creates a new user account and returns access and refresh tokens.

{
  "email": "newuser@example.com",
  "password": "securePassword123",
  "firstName": "Jane",
  "lastName": "Smith"
}
StatusDescription
200AuthResponse with tokens and user profile
400Invalid input or email already registered

POST /api/v1/auth/refresh

Obtains a new access token using a valid refresh token.

{
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9..."
}
StatusDescription
200AuthResponse with new access token
401Invalid or expired refresh token

POST /api/v1/auth/logout

Revokes the refresh token and terminates the session.

{
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9..."
}
StatusDescription
204Logout successful, no content returned

Security Notes

  • Client IP is extracted from X-Forwarded-For or RemoteAddr for audit logging
  • User-Agent header is captured for device fingerprinting
  • Failed login attempts trigger account lockout after the configured threshold (default: 5 attempts, 30-minute lockout)
OverviewUser Endpoints