API REFERENCE

Authentication API

Core authentication endpoints for login, registration, and token management.

Endpoints

POST/api/v1/auth/login

Authenticate a user with email and password. Returns access and refresh tokens.

Rate limit: 5 attempts / 15 min / IP

Request Body

json

{
  "email": "user@example.com",
  "password": "secure-password",
  "deviceFingerprint": "optional-device-id"
}

Response

json

{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "emailVerified": true,
    "mfaEnabled": true
  },
  "tokens": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "rt_xyz789...",
    "expiresIn": 900
  },
  "requiresMfa": false
}

POST/api/v1/auth/register

Create a new user account. Sends verification email.

Rate limit: 3 attempts / hour / IP

Request Body

json

{
  "email": "newuser@example.com",
  "password": "SecureP@ss123!",
  "name": "John Doe"
}

Response

json

{
  "user": {
    "id": "usr_def456",
    "email": "newuser@example.com",
    "emailVerified": false
  },
  "message": "Verification email sent"
}

POST/api/v1/auth/refresh

Exchange a refresh token for new access and refresh tokens.

Rate limit: 10 requests / min / user

Request Body

json

{
  "refreshToken": "rt_xyz789..."
}

Response

json

{
  "tokens": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "rt_new123...",
    "expiresIn": 900
  }
}

POST/api/v1/auth/logout

Invalidate the current session and refresh token.

Request Body

json

{
  "refreshToken": "rt_xyz789..."
}

Response

json

{
  "success": true
}

POST/api/v1/auth/mfa/verify

Verify MFA code (TOTP or WebAuthn) to complete authentication.

Rate limit: 5 attempts / min / user

Request Body

json

{
  "mfaToken": "mfa_pending_abc...",
  "code": "123456",
  "type": "totp"
}

Response

json

{
  "user": { ... },
  "tokens": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "rt_xyz789...",
    "expiresIn": 900
  }
}

Error Responses

json

{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid email or password",
    "status": 401
  }
}

// Common error codes:
// INVALID_CREDENTIALS - Wrong email/password
// RATE_LIMITED - Too many attempts
// MFA_REQUIRED - MFA verification needed
// TOKEN_EXPIRED - Access token expired
// INVALID_TOKEN - Malformed or invalid token