Authentication API

The Authentication API provides secure user authentication with support for email/password registration, OAuth providers, email verification, password resets, and session management.

Base URL

All authentication endpoints are prefixed with /api/auth

Public Configuration

Get Public Auth Config

curl https://your-app.region.insforge.app/api/auth/public-config

Retrieve public authentication configuration including OAuth providers and password requirements. Response

oAuthProviders

array

List of configured OAuth providers

Show properties

provider

string

OAuth provider name (google, github, discord, linkedin, facebook, instagram, tiktok, apple, x, spotify, microsoft)

useSharedKey

boolean

Whether using InsForge shared OAuth keys

requireEmailVerification

boolean

Whether email verification is required before login

passwordMinLength

integer

Minimum password length (4-128)

requireNumber

boolean

Whether passwords must contain a number

requireLowercase

boolean

Whether passwords must contain lowercase letters

requireUppercase

boolean

Whether passwords must contain uppercase letters

requireSpecialChar

boolean

Whether passwords must contain special characters

verifyEmailMethod

string

Email verification method: code (6-digit OTP) or link (magic link)

resetPasswordMethod

string

Password reset method: code (6-digit OTP + exchange) or link (magic link)

{
  "oAuthProviders": [
    {
      "provider": "google",
      "useSharedKey": true
    },
    {
      "provider": "github",
      "useSharedKey": false
    }
  ],
  "requireEmailVerification": true,
  "passwordMinLength": 8,
  "requireNumber": true,
  "requireLowercase": true,
  "requireUppercase": false,
  "requireSpecialChar": false,
  "verifyEmailMethod": "code",
  "resetPasswordMethod": "link"
}

Register New User

curl -X POST https://your-app.region.insforge.app/api/auth/users?client_type=web \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123",
    "name": "John Doe"
  }'

Create a new user account with email and password. Query Parameters

client_type

string

default:"web"

Client type determines token delivery:

web: Refresh token in httpOnly cookie, csrfToken in response
mobile/desktop: refreshToken in response body

Body Parameters

string

required

User’s email address

password

string

required

Password meeting configured requirements

name

string

User’s display name

Response

user

object

User object with profile information

accessToken

string

JWT authentication token (null if email verification required)

csrfToken

string

CSRF token for refresh endpoint (web clients only)

refreshToken

string

Refresh token (mobile/desktop clients only)

requireEmailVerification

boolean

Whether email verification is required before login

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "profile": {
      "name": "John Doe"
    },
    "emailVerified": false,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": null,
  "csrfToken": null,
  "refreshToken": null,
  "requireEmailVerification": true
}

curl -X POST https://your-app.region.insforge.app/api/auth/sessions?client_type=web \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123"
  }'

Authenticate user and return access token. Query Parameters

client_type

string

default:"web"

Client type: web, mobile, or desktop

Body Parameters

string

required

User’s email address

password

string

required

User’s password

Response

user

object

User object with profile information

accessToken

string

JWT authentication token

csrfToken

string

CSRF token (web clients only)

refreshToken

string

Refresh token (mobile/desktop clients only)

redirectTo

string

Optional URL to redirect after login

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "profile": {
      "name": "John Doe",
      "avatar_url": "https://example.com/avatar.jpg"
    },
    "emailVerified": true,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "csrfToken": "abc123def456"
}

Refresh Access Token

curl -X POST https://your-app.region.insforge.app/api/auth/refresh?client_type=web \
  -H "X-CSRF-Token: abc123def456" \
  -H "Cookie: refreshToken=..." \
  -H "Content-Type: application/json"

Refresh access token using refresh token. Query Parameters

client_type

string

default:"web"

Client type: web (uses cookie + CSRF), mobile/desktop (uses body)

Headers (Web clients only)

X-CSRF-Token

string

required

CSRF token from login/register response

Body Parameters (Mobile/Desktop only)

refreshToken

string

required

Refresh token from previous authentication

Response

user

object

User object

accessToken

string

New JWT access token

csrfToken

string

New CSRF token (web clients)

refreshToken

string

New refresh token (mobile/desktop clients - must replace old token)

Logout

curl -X POST https://your-app.region.insforge.app/api/auth/logout

Logout user and clear refresh token cookie. Response

{
  "success": true,
  "message": "Logged out successfully"
}

Get Current User

curl https://your-app.region.insforge.app/api/auth/sessions/current \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get currently authenticated user info from JWT token. Response

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "role": "authenticated"
  }
}

Email Verification

Send Verification Email

curl -X POST https://your-app.region.insforge.app/api/auth/email/send-verification \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

Send email verification code or link based on configuration. Body Parameters

string

required

Email address to verify

Response

{
  "success": true,
  "message": "If your email is registered, we have sent you a verification code. Please check your inbox."
}

Verify Email

curl -X POST https://your-app.region.insforge.app/api/auth/email/verify?client_type=web \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "otp": "123456"
  }'

Verify email with code or token. Body Parameters

string

Email address (required for code verification, omit for link verification)

otp

string

required

6-digit code or 64-character hex token from magic link

Response

user

object

User object

accessToken

string

JWT authentication token

csrfToken

string

CSRF token (web clients)

refreshToken

string

Refresh token (mobile/desktop clients)

Password Reset

Send Password Reset

curl -X POST https://your-app.region.insforge.app/api/auth/email/send-reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

Send password reset code or link. Body Parameters

string

required

Email address for password reset

Response

{
  "success": true,
  "message": "If your email is registered, we have sent you a password reset link. Please check your inbox."
}

Exchange Reset Code for Token

curl -X POST https://your-app.region.insforge.app/api/auth/email/exchange-reset-password-token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "code": "123456"
  }'

Exchange 6-digit code for reset token (code method only). Body Parameters

string

required

User’s email address

code

string

required

6-digit code from email

Response

{
  "token": "a1b2c3d4e5f6...",
  "expiresAt": "2024-01-15T11:30:00Z"
}

Reset Password

curl -X POST https://your-app.region.insforge.app/api/auth/email/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "newPassword": "newSecurePassword123",
    "otp": "a1b2c3d4e5f6..."
  }'

Reset password with token. Body Parameters

newPassword

string

required

New password meeting requirements

otp

string

required

Reset token from magic link or exchange endpoint

Response

{
  "message": "Password reset successfully"
}

User Profiles

Get User Profile by ID

curl https://your-app.region.insforge.app/api/auth/profiles/550e8400-e29b-41d4-a716-446655440000

Get public profile for any user (no authentication required). Path Parameters

userId

string

required

User UUID

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "profile": {
    "name": "John Doe",
    "avatar_url": "https://example.com/avatar.jpg"
  }
}

Update Current User Profile

curl -X PATCH https://your-app.region.insforge.app/api/auth/profiles/current \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "name": "Jane Doe",
      "avatar_url": "https://example.com/new-avatar.jpg",
      "bio": "Software developer"
    }
  }'

Update authenticated user’s profile. Body Parameters

profile

object

required

Profile data including name, avatar_url, and custom fields

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "profile": {
    "name": "Jane Doe",
    "avatar_url": "https://example.com/new-avatar.jpg",
    "bio": "Software developer"
  }
}

OAuth Authentication

Initiate OAuth Flow

curl "https://your-app.region.insforge.app/api/auth/oauth/google?redirect_uri=https://myapp.com/callback&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

Generate OAuth authorization URL with PKCE support. Path Parameters

provider

string

required

OAuth provider: google, github, discord, linkedin, facebook, instagram, tiktok, apple, x, spotify, microsoft

Query Parameters

redirect_uri

string

required

URL to redirect after authentication (receives insforge_code parameter)

code_challenge

string

PKCE code challenge (Base64URL(SHA256(code_verifier))) for mobile/desktop apps

Response

{
  "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&response_type=code&scope=openid+email+profile&state=..."
}

Exchange OAuth Code

curl -X POST https://your-app.region.insforge.app/api/auth/oauth/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "code": "insforge_code_received_from_callback",
    "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
  }'

Exchange insforge_code for access and refresh tokens (PKCE flow). Body Parameters

code

string

required

insforge_code from OAuth callback redirect

code_verifier

string

required

Original code_verifier (43-128 characters)

Response

user

object

User object

accessToken

string

JWT access token

refreshToken

string

Refresh token

Admin Endpoints

curl -X POST https://your-app.region.insforge.app/api/auth/admin/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "adminPassword"
  }'

Authenticate as admin user for dashboard access.

List All Users

curl https://your-app.region.insforge.app/api/auth/users?limit=10&offset=0&search=john \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN"

List all users with pagination (admin only). Query Parameters

offset

string

default:"0"

Number of records to skip

limit

string

default:"10"

Maximum records to return

string

Search by email or name

Generate Anonymous Token

curl -X POST https://your-app.region.insforge.app/api/auth/tokens/anon \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN"

Generate non-expiring anonymous token for public API access (admin only). Response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "message": "Anonymous token generated successfully (never expires)"
}

Core APIs

Management APIs

Authentication API

Base URL

Public Configuration

Get Public Auth Config

Register New User

Refresh Access Token

Logout

Get Current User

Email Verification

Send Verification Email

Verify Email

Password Reset

Send Password Reset

Exchange Reset Code for Token

Reset Password

User Profiles

Get User Profile by ID

Update Current User Profile

OAuth Authentication

Initiate OAuth Flow

Exchange OAuth Code

Admin Endpoints

List All Users

Generate Anonymous Token

Core APIs

Management APIs

Documentation Index

​Base URL

​Public Configuration

​Get Public Auth Config

​User Registration & Login

​Register New User

​User Login

​Refresh Access Token

​Logout

​Get Current User

​Email Verification

​Send Verification Email

​Verify Email

​Password Reset

​Send Password Reset

​Exchange Reset Code for Token

​Reset Password

​User Profiles

​Get User Profile by ID

​Update Current User Profile

​OAuth Authentication

​Initiate OAuth Flow

​Exchange OAuth Code

​Admin Endpoints

​Admin Login

​List All Users

​Generate Anonymous Token

Base URL

Public Configuration

Get Public Auth Config

User Registration & Login

Register New User

User Login

Refresh Access Token

Logout

Get Current User

Email Verification

Send Verification Email

Verify Email

Password Reset

Send Password Reset

Exchange Reset Code for Token

Reset Password

User Profiles

Get User Profile by ID

Update Current User Profile

OAuth Authentication

Initiate OAuth Flow

Exchange OAuth Code

Admin Endpoints

Admin Login

List All Users

Generate Anonymous Token