Auth Rail

Auth Rail

Authentication, session management, and MFA.

Overview

The Auth Rail provides endpoints for user authentication, session management, multi-factor authentication, and password management.

Base URL

/api/v1/auth

Endpoints

Login

POST /api/v1/auth/login

Authenticate user and create session.

Request Body:

{
  "email": "user@example.com",
  "password": "********",
  "rememberMe": true
}

Response:

{
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJl...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "user": {
      "id": "user_123",
      "email": "user@example.com",
      "name": "Ahmad Abdullah",
      "roles": ["admin"]
    },
    "mfaRequired": false
  }
}

Refresh Token

POST /api/v1/auth/refresh

Refresh access token.

Request Body:

{
  "refreshToken": "dGhpcyBpcyBhIHJlZnJl..."
}

Logout

POST /api/v1/auth/logout

Invalidate session.

Register

POST /api/v1/auth/register

Register new user.

Request Body:

{
  "email": "newuser@example.com",
  "password": "SecureP@ss123",
  "name": "New User",
  "tenantId": "tenant_123"
}

Verify Email

POST /api/v1/auth/verify-email

Verify email address.

Request Body:

{
  "token": "verification_token_here"
}

Forgot Password

POST /api/v1/auth/forgot-password

Request password reset.

Request Body:

{
  "email": "user@example.com"
}

Reset Password

POST /api/v1/auth/reset-password

Reset password with token.

Request Body:

{
  "token": "reset_token_here",
  "password": "NewSecureP@ss123"
}

Change Password

POST /api/v1/auth/change-password

Change current user password.

Request Body:

{
  "currentPassword": "OldP@ss123",
  "newPassword": "NewSecureP@ss123"
}

Setup MFA

POST /api/v1/auth/mfa/setup

Set up multi-factor authentication.

Request Body:

{
  "method": "TOTP"
}

Response:

{
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qrCode": "data:image/png;base64,...",
    "backupCodes": ["12345678", "87654321", "..."]
  }
}

Verify MFA

POST /api/v1/auth/mfa/verify

Verify MFA code during login.

Request Body:

{
  "code": "123456",
  "trustDevice": true
}

Get Sessions

GET /api/v1/auth/sessions

List active sessions.

Revoke Session

DELETE /api/v1/auth/sessions/:sessionId

Revoke a specific session.

MFA Methods

Method	Description
TOTP	Time-based OTP (Google Authenticator)
SMS	SMS OTP
EMAIL	Email OTP
HARDWARE	Hardware key (FIDO2)

Token Types

Type	Lifetime	Use Case
Access Token	1 hour	API requests
Refresh Token	7 days	Token refresh
ID Token	1 hour	User identity

Events

Event	Description
auth.login.success	Successful login
auth.login.failed	Failed login attempt
auth.logout	User logged out
auth.password.changed	Password changed
auth.mfa.enabled	MFA enabled

See Also

• OAuth2 Rail - OAuth 2.0 flows
• SAML Rail - Enterprise SSO