Authentication API Reference

Complete reference for all authentication-related API endpoints.

Base URL

https://api.yourdomain.com

Authentication Headers

All authenticated endpoints require:

Authorization: Bearer <access-token>
Content-Type: application/json

Endpoints

Register User

POST /auth/register

Register a new user account.

Request Body:

{
  "email": "[email protected]",
  "password": "SecurePassword123!",
  "name": "John Doe",
  "acceptTerms": true
}

Response:

{
  "message": "Registration successful. Please verify your email.",
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}

Status Codes:

• 201 - Created successfully
• 400 - Validation error
• 409 - Email already exists

---

Login

POST /auth/login

Authenticate a user and receive tokens.

Request Body:

{
  "email": "[email protected]",
  "password": "SecurePassword123!"
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "name": "John Doe",
    "role": "user"
  },
  "requiresMfa": false
}

Status Codes:

• 200 - Login successful
• 401 - Invalid credentials
• 423 - Account locked

---

Logout

POST /auth/logout

Invalidate the current refresh token.

Headers:

Authorization: Bearer <access-token>

Response:

{
  "message": "Logged out successfully"
}

---

Refresh Token

POST /auth/refresh

Refresh access token using refresh token.

Headers:

Cookie: refreshToken=<refresh-token>

Response:

{
  "accessToken": "new-access-token",
  "refreshToken": "new-refresh-token"
}

---

Verify Email

POST /auth/verify-email

Verify user email address.

Request Body:

{
  "token": "verification-token-from-email"
}

Response:

{
  "message": "Email verified successfully"
}

---

Forgot Password

POST /auth/forgot-password

Request a password reset email.

Request Body:

{
  "email": "[email protected]"
}

Response:

{
  "message": "If an account exists with this email, a password reset link has been sent."
}

---

Reset Password

POST /auth/reset-password

Reset password using reset token.

Request Body:

{
  "token": "reset-token-from-email",
  "password": "NewSecurePassword123!"
}

Response:

{
  "message": "Password reset successfully"
}

---

Setup MFA (TOTP)

POST /auth/setup-totp

Setup TOTP-based multi-factor authentication.

Headers:

Authorization: Bearer <access-token>

Response:

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "backupCodes": ["XXXX-XXXX", "XXXX-XXXX", "XXXX-XXXX", "XXXX-XXXX"]
}

---

Verify MFA

POST /auth/verify-mfa

Verify MFA code during login.

Request Body:

{
  "tempToken": "temporary-token-from-login",
  "code": "123456"
}

Response:

{
  "accessToken": "full-access-token",
  "refreshToken": "full-refresh-token",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]"
  }
}

---

Get Current User

GET /user/profile

Get the currently authenticated user's profile.

Headers:

Authorization: Bearer <access-token>

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "name": "John Doe",
  "role": "user",
  "emailVerified": true,
  "mfaEnabled": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T00:00:00Z"
}

---

Update Profile

PUT /user/profile

Update the current user's profile.

Headers:

Authorization: Bearer <access-token>

Request Body:

{
  "name": "John Updated",
  "bio": "Software developer"
}

Response:

{
  "message": "Profile updated successfully",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "John Updated",
    "bio": "Software developer"
  }
}

---

Change Password

POST /user/change-password

Change password for authenticated user.

Headers:

Authorization: Bearer <access-token>

Request Body:

{
  "currentPassword": "CurrentPassword123!",
  "newPassword": "NewSecurePassword456!"
}

Response:

{
  "message": "Password changed successfully"
}

---

Get Active Sessions

GET /user/sessions

Get all active sessions for the user.

Headers:

Authorization: Bearer <access-token>

Response:

[
  {
    "id": "session-uuid-1",
    "device": "Chrome on Windows",
    "ip": "192.168.1.1",
    "location": "New York, US",
    "createdAt": "2024-01-15T10:00:00Z",
    "lastActive": "2024-01-15T10:30:00Z",
    "current": true
  },
  {
    "id": "session-uuid-2",
    "device": "Safari on iPhone",
    "ip": "192.168.1.2",
    "location": "New York, US",
    "createdAt": "2024-01-14T15:00:00Z",
    "lastActive": "2024-01-15T09:00:00Z",
    "current": false
  }
]

---

Revoke Session

DELETE /user/sessions/:id

Revoke a specific session.

Headers:

Authorization: Bearer <access-token>

Response:

{
  "message": "Session revoked successfully"
}

---

Revoke All Sessions

DELETE /user/sessions

Revoke all sessions except the current one.

Headers:

Authorization: Bearer <access-token>

Response:

{
  "message": "All other sessions revoked successfully"
}

---

Error Responses

All endpoints return standard error responses:

{
  "statusCode": 400,
  "message": "Validation error message",
  "error": "Bad Request"
}

Common Error Codes

Code	Description
400	Bad Request - Invalid input
401	Unauthorized - Invalid or expired token
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
409	Conflict - Resource already exists
423	Locked - Account is locked
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Rate Limits

Endpoint	Limit	Window
/auth/login	5	15 minutes
/auth/register	10	15 minutes
/auth/forgot-password	3	1 hour
Authenticated endpoints	100	1 minute

Related Documentation

• Authentication Concepts - Authentication system overview
• Security Best Practices - Security hardening