Authentication API Reference

Complete API reference for the Authentication module.

User Registration

Create User (Local)

POST /authentication/local/new

Request Body:

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

Response:

{
  "user": {
    "email": "user@example.com",
    "active": true,
    "isVerified": false,
    "_id": "..."
  }
}

Authentication

Login (Local)

POST /authentication/local

Request Body:

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

Response:

{
  "userId": "...",
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "aDYLqHPw6yK+GTNsWApA..."
}

Logout

POST /authentication/logout
Authorization: Bearer {accessToken}

Refresh Token

POST /authentication/renew
Authorization: Bearer {refreshToken}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "aDYLqHPw6yK+GTNsWApA..."
}

Password Management

Forgot Password

POST /authentication/forgot-password

Request Body:

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

Reset Password

POST /authentication/reset-password

Request Body:

{
  "passwordResetToken": "token-from-email",
  "password": "newPassword123"
}

Change Password

POST /authentication/local/change-password
Authorization: Bearer {accessToken}

Request Body:

{
  "oldPassword": "currentPassword",
  "newPassword": "newPassword123"
}

Email Management

Change Email

POST /authentication/local/change-email
Authorization: Bearer {accessToken}

Request Body:

{
  "newEmail": "newemail@example.com"
}

Resend Verification

POST /authentication/local/resend-verification

Request Body:

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

Verification Webhooks

Verify Email

GET /hook/authentication/verify-email/{verificationToken}

Verify Email Change

GET /hook/authentication/verify-change-email/{verificationToken}

OAuth Endpoints

Initialize OAuth

GET /authentication/init/{provider}

Providers: google, facebook, github, apple, microsoft, twitter, linkedin, slack, twitch, gitlab, bitbucket, reddit, figma

Response:

{
  "result": "https://accounts.google.com/o/oauth2/v2/auth?..."
}

OAuth Callback

GET /hook/authentication/{provider}

Handled automatically after OAuth flow.

Two-Factor Authentication

Enable 2FA

POST /authentication/twoFa/enable
Authorization: Bearer {accessToken}

Verify 2FA

POST /authentication/twoFa/verify

Request Body:

{
  "code": "123456"
}

Generate Backup Codes

POST /authentication/twoFa/backup-codes
Authorization: Bearer {accessToken}

Magic Link

Request Magic Link

POST /authentication/magic-link

Request Body:

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

Verify Magic Link

GET /hook/authentication/magic-link/{token}

User Information

Get Current User

GET /authentication/user
Authorization: Bearer {accessToken}

Response:

{
  "user": {
    "email": "user@example.com",
    "active": true,
    "isVerified": true,
    "hasTwoFA": false,
    "_id": "..."
  }
}

Error Responses

Status	Description
400	Invalid request body
401	Invalid credentials or token
403	Account blocked or unverified
429	Rate limit exceeded