---
title: Authentication API Reference
description: User authentication and session management via REST API
---

## Overview

The Authentication API provides endpoints for user registration, login, email verification, password reset, and OAuth integration.

## Headers

For authenticated function invocations:
```bash
Authorization: Bearer your-jwt-token-or-anon-key
Content-Type: application/json
```

For admin endpoints:
```bash
Authorization: Bearer admin-jwt-token-Or-API-Key
Content-Type: application/json
```

---

## Register User

Create a new user account.

```
POST /api/auth/users
```

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `client_type` | string | No | Client type: `web` (default), `mobile`, `desktop`, or `server` |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | User email address |
| `password` | string | Yes | Password (must meet configured requirements) |
| `name` | string | No | User display name |
| `redirectTo` | string | No | Used for link-based email verification. The email link always opens an InsForge backend endpoint first; after the token is verified, InsForge redirects the browser to this URL with the verification result. Required when `verifyEmailMethod` is `link`. This URL must be included in `allowedRedirectUrls`. Recommended: use your app's sign-in page. |

### Example (Web Client)

```bash
curl -X POST "https://your-app.insforge.app/api/auth/users" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "name": "John Doe",
    "redirectTo": "http://localhost:3000/sign-in"
  }'
```

### Example (Non-Web Client)

```bash
curl -X POST "https://your-app.insforge.app/api/auth/users?client_type=mobile" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "name": "John Doe",
    "redirectTo": "myapp://sign-in"
  }'
```

### Response (Web Client)

```json
{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": false,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "csrfToken": "abc123...",
  "requireEmailVerification": false
}
```

### Response (Non-Web Client)

```json
{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": false,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "requireEmailVerification": false
}
```

<Note>
- For **web clients**: A `csrfToken` is returned and the refresh token is stored in an httpOnly cookie.
- For **non-web clients** (`mobile`, `desktop`, `server`): A `refreshToken` is returned directly in the response. Store it securely in your client or server runtime.
- Use **`server`** for trusted server-side callers such as SSR apps, BFFs, or CLIs that cannot rely on browser cookies.
- If `requireEmailVerification` is `true`, `accessToken` and tokens will be `null` and the user must verify their email before logging in.
</Note>

---

## Sign In

Authenticate user and get access token.

```
POST /api/auth/sessions
```

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `client_type` | string | No | Client type: `web` (default), `mobile`, `desktop`, or `server` |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | User email address |
| `password` | string | Yes | User password |

### Example (Web Client)

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

### Example (Non-Web Client)

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

### Response (Web Client)

```json
{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "csrfToken": "abc123..."
}
```

### Response (Non-Web Client)

```json
{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
```

<Note>
- For **web clients**: A `csrfToken` is returned and the refresh token is stored in an httpOnly cookie. Include the `csrfToken` in the `X-CSRF-Token` header when calling `/api/auth/refresh`.
- For **non-web clients** (`mobile`, `desktop`, `server`): A `refreshToken` is returned directly. Store it securely and include it in the request body when calling `/api/auth/refresh`.
</Note>

---

## Refresh Token

Refresh access token using refresh token.

```
POST /api/auth/refresh
```

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `client_type` | string | No | Client type: `web` (default), `mobile`, `desktop`, or `server` |

### Headers (Web Client)

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| `X-CSRF-Token` | string | Yes | CSRF token received from login/register response |

### Request Body (Non-Web Client)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `refreshToken` | string | Yes | Refresh token received from login/register response |

### Example (Web Client)

```bash
curl -X POST "https://your-app.insforge.app/api/auth/refresh" \
  -H "X-CSRF-Token: abc123..." \
  --cookie "refresh_token=..."
```

### Example (Non-Web Client)

```bash
curl -X POST "https://your-app.insforge.app/api/auth/refresh?client_type=mobile" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }'
```

### Response (Web Client)

```json
{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "csrfToken": "def456..."
}
```

### Response (Non-Web Client)

```json
{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
```

<Note>
Token rotation is implemented for security:
- **Web clients**: Each refresh returns a new `csrfToken` that must be used for subsequent refresh requests.
- **Non-web clients** (`mobile`, `desktop`, `server`): Each refresh returns a new `refreshToken`. You must persist this new token and use it for the next refresh. Update the `accessToken` in memory.
</Note>

---

## Logout

Logout and clear refresh token cookie.

```
POST /api/auth/logout
```

### Example

```bash
curl -X POST "https://your-app.insforge.app/api/auth/logout"
```

### Response

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

---

## Get Current User

Get the currently authenticated user's info from JWT token.

This REST endpoint does not refresh expired access tokens by itself.

- For raw REST clients, call `POST /api/auth/refresh` when needed.
- For browser apps using the TypeScript SDK, call `auth.getCurrentUser()` during startup. The SDK will use the httpOnly refresh cookie automatically when it can refresh the session.
- This automatic refresh behavior is browser-only. Server, mobile, and other non-browser clients should refresh explicitly.

```
GET /api/auth/sessions/current
```

### Example

```bash
curl "https://your-app.insforge.app/api/auth/sessions/current" \
  -H "Authorization: Bearer your-jwt-token"
```

### Response

```json
{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "role": "authenticated"
  }
}
```

---

## Update Profile

Update the current user's profile.

```
PATCH /api/auth/profiles/current
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `profile` | object | Yes | Profile data (name, avatar_url, custom fields) |

### Example

```bash
curl -X PATCH "https://your-app.insforge.app/api/auth/profiles/current" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "name": "John Doe",
      "avatar_url": "https://example.com/avatar.jpg"
    }
  }'
```

### Response

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "profile": {
    "name": "John Doe",
    "avatar_url": "https://example.com/avatar.jpg"
  }
}
```

---

## Get User Profile

Get public profile information for a user by ID.

```
GET /api/auth/profiles/{userId}
```

### Example

```bash
curl "https://your-app.insforge.app/api/auth/profiles/123e4567-e89b-12d3-a456-426614174000"
```

### Response

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "profile": {
    "name": "John Doe",
    "avatar_url": "https://example.com/avatar.jpg"
  }
}
```

---

## Email Verification

### Send Verification Email

```
POST /api/auth/email/send-verification
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | User email address |
| `redirectTo` | string | No | Used for link-based email verification. The email link always opens an InsForge backend endpoint first; after the token is verified, InsForge redirects the browser to this URL with the verification result. Required when `verifyEmailMethod` is `link`. This URL must be included in `allowedRedirectUrls`. Recommended: use your app's sign-in page. |

### Example

```bash
curl -X POST "https://your-app.insforge.app/api/auth/email/send-verification" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "redirectTo": "http://localhost:3000/sign-in"
  }'
```

### Response

```json
{
  "success": true,
  "message": "If your email is registered, we have sent you a verification code/link."
}
```

### Verify Email

```
POST /api/auth/email/verify
```

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `client_type` | string | No | Client type: `web` (default), `mobile`, `desktop`, or `server` |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | User email address |
| `otp` | string | Yes | 6-digit verification code |

For link-based verification, email clicks use:

```
GET /api/auth/email/verify-link?token=...
```

That browser-oriented GET flow verifies the token on the backend and redirects to the stored `redirectTo` URL. `POST /api/auth/email/verify` is the JSON API for 6-digit code submission.

Handle the browser redirect like this:

- Success: `?insforge_status=success&insforge_type=verify_email`
- Error: `?insforge_status=error&insforge_type=verify_email&insforge_error=...`
- `insforge_status`: Result of the browser link flow. For verification, values are `success` or `error`.
- `insforge_type`: Flow identifier. For verification links this is always `verify_email`.
- `insforge_error`: Present only when `insforge_status=error`. Human-readable error message for display or logging.
- Recommended handling: use your sign-in page as `redirectTo`. When `insforge_status=success`, show a confirmation message and ask the user to sign in with their email and password.
- If `redirectTo` is not allowlisted, InsForge returns a `400` error whose message includes the rejected URL and whose `nextActions` tells you to add it to `allowedRedirectUrls`.

### Example (Web Client)

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

### Example (Non-Web Client)

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

### Response (Web Client)

```json
{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "csrfToken": "abc123..."
}
```

### Response (Non-Web Client)

```json
{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
```

---

## Password Reset

### Send Reset Email

```
POST /api/auth/email/send-reset-password
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | User email address |
| `redirectTo` | string | No | Used for link-based password reset. The email link always opens an InsForge backend endpoint first; InsForge then redirects the browser to this URL with the reset `token` in the query string so your app can render its own reset-password page. Required when `resetPasswordMethod` is `link`. This URL must be included in `allowedRedirectUrls`. Recommended: use your app's dedicated reset-password page. |

### Example

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

### Exchange Code for Token (Code Method Only)

```
POST /api/auth/email/exchange-reset-password-token
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | User email address |
| `code` | string | Yes | 6-digit code from email |

### Example

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

### Response

```json
{
  "token": "abc123...",
  "expiresAt": "2024-01-15T11:00:00Z"
}
```

### Reset Password

```
POST /api/auth/email/reset-password
```

For link-based password reset, email clicks use:

```
GET /api/auth/email/reset-password-link?token=...
```

That browser-oriented GET flow validates the token on the backend and redirects to the stored `redirectTo` URL with the reset token in the query string. `POST /api/auth/email/reset-password` remains the JSON API that accepts the new password.

Handle the browser redirect like this:

- Ready to reset: `?token=...&insforge_status=ready&insforge_type=reset_password`
- Error: `?insforge_status=error&insforge_type=reset_password&insforge_error=...`
- `token`: Present only when `insforge_status=ready`. Pass this value to `POST /api/auth/email/reset-password` as `otp`.
- `insforge_status`: Result of the browser link flow. For reset links, values are `ready` or `error`.
- `insforge_type`: Flow identifier. For reset links this is always `reset_password`.
- `insforge_error`: Present only when `insforge_status=error`. Human-readable error message for display or logging.
- Your app should only render the reset-password form when `insforge_status=ready` and `token` is present.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `newPassword` | string | Yes | New password |
| `otp` | string | Yes | Reset token from either the code exchange endpoint or the magic link URL |

### Example

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

### Response

```json
{
  "message": "Password reset successfully"
}
```

---

## OAuth Authentication

OAuth authentication now uses the PKCE (Proof Key for Code Exchange) flow for enhanced security. Instead of returning tokens directly in the redirect URL, an authorization code is returned which must be exchanged for tokens.

### Initiate OAuth Flow

```
GET /api/auth/oauth/{provider}
```

For custom providers configured in the dashboard, use:

```
GET /api/auth/oauth/custom/{key}
```

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `redirect_uri` | string | Yes | URL to redirect after authentication |
| `code_challenge` | string | Yes | PKCE code challenge (Base64 URL-encoded SHA256 hash of code_verifier) |
| Other string query params | string | No | Provider-specific OAuth hints, such as Google's `prompt=select_account` |

<Note>
  Extra query params are forwarded as provider-specific hints only when they do not collide with
  server-owned OAuth fields. Do not pass `client_id`, `redirect_uri`, `code_challenge`, `state`,
  `response_type`, or `scope`; InsForge/provider-generated values win and colliding client
  values are ignored.
</Note>

### Supported Providers

- `google`
- `github`
- `discord`
- `linkedin`
- `facebook`
- `apple`
- `microsoft`
- `x`
- `spotify`
- Any custom provider key returned by `GET /api/auth/public-config` in `customOAuthProviders`

### Example

```bash
# Generate code_verifier (random string, 43-128 characters)
CODE_VERIFIER=$(openssl rand -base64 32 | tr -d '=' | tr '/+' '_-')

# Generate code_challenge (SHA256 hash of code_verifier, Base64 URL-encoded)
CODE_CHALLENGE=$(echo -n $CODE_VERIFIER | openssl dgst -sha256 -binary | base64 | tr -d '=' | tr '/+' '_-')

curl "https://your-app.insforge.app/api/auth/oauth/google?redirect_uri=https://myapp.com/callback&code_challenge=$CODE_CHALLENGE&prompt=select_account"
```

```bash
# Custom provider example
curl "https://your-app.insforge.app/api/auth/oauth/custom/acme?redirect_uri=https://myapp.com/callback&code_challenge=$CODE_CHALLENGE"
```

### Response

```json
{
  "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=..."
}
```

### OAuth Callback

After the user authenticates with the provider, they will be redirected to your `redirect_uri` with an authorization code:

```
https://myapp.com/callback?insforge_code=abc123...
```

<Note>
The `insforge_code` is a temporary authorization code that must be exchanged for tokens using the `/api/auth/oauth/exchange` endpoint.
</Note>

---

### Exchange Code for Tokens

Exchange the authorization code for access and refresh tokens.

```
POST /api/auth/oauth/exchange
```

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `client_type` | string | No | Client type: `web` (default), `mobile`, `desktop`, or `server` |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `code` | string | Yes | The `insforge_code` received in the callback |
| `code_verifier` | string | Yes | The original code_verifier used to generate the code_challenge |

### Example

```bash
curl -X POST "https://your-app.insforge.app/api/auth/oauth/exchange?client_type=mobile" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "abc123...",
    "code_verifier": "your-original-code-verifier"
  }'
```

### Response

```json
{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true,
    "providers": ["google"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
```

<Note>
- For **web clients**: The `refreshToken` will be `null` and a `csrfToken` is returned instead. The refresh token is stored in an httpOnly cookie.
- For **non-web clients** (`mobile`, `desktop`, `server`): A `refreshToken` is returned directly. Store it securely.
</Note>

---

### Complete OAuth Flow Example (Non-Web)

```swift
// 1. Generate PKCE code verifier and challenge
let codeVerifier = generateRandomString(length: 43)
let codeChallenge = sha256(codeVerifier).base64URLEncoded()

// 2. Initiate OAuth flow
let authURL = "https://your-app.insforge.app/api/auth/oauth/google" +
    "?redirect_uri=myapp://callback" +
    "&code_challenge=\(codeChallenge)"

// 3. Open browser/WebView and wait for callback
// User completes authentication...

// 4. Handle callback with insforge_code
// myapp://callback?insforge_code=abc123...

// 5. Exchange code for tokens
let response = POST("/api/auth/oauth/exchange?client_type=mobile", body: {
    "code": insforgeCode,
    "code_verifier": codeVerifier
})

// 6. Store tokens
accessToken = response.accessToken
refreshToken = response.refreshToken  // Persist securely
```

---

## Public Configuration

Get public authentication settings (no auth required).

```
GET /api/auth/public-config
```

### Example

```bash
curl "https://your-app.insforge.app/api/auth/public-config"
```

### Response

```json
{
  "oAuthProviders": ["google", "github"],
  "customOAuthProviders": ["acme"],
  "requireEmailVerification": true,
  "passwordMinLength": 8,
  "requireNumber": true,
  "requireLowercase": true,
  "requireUppercase": false,
  "requireSpecialChar": false,
  "verifyEmailMethod": "code",
  "resetPasswordMethod": "link"
}
```

---

## Admin Endpoints

These endpoints require `project_admin` role.

### List All Users

```
GET /api/auth/users?offset=0&limit=10&search=john
```

### Get User by ID

```
GET /api/auth/users/{userId}
```

### Delete Users

```bash
curl -X DELETE "https://your-app.insforge.app/api/auth/users" \
  -H "Authorization: Bearer admin-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"userIds": ["user-id-1", "user-id-2"]}'
```

### Generate Anonymous Token

```
POST /api/auth/tokens/anon
```

### Get Auth Configuration

Get current authentication settings (admin only).

```
GET /api/auth/config
```

#### Example

```bash
curl "https://your-app.insforge.app/api/auth/config" \
  -H "Authorization: Bearer admin-jwt-token"
```

#### Response

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "requireEmailVerification": true,
  "passwordMinLength": 8,
  "requireNumber": true,
  "requireLowercase": true,
  "requireUppercase": false,
  "requireSpecialChar": false,
  "verifyEmailMethod": "code",
  "resetPasswordMethod": "link",
  "allowedRedirectUrls": ["https://myapp.com/dashboard", "https://*.myapp.com"],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

`allowedRedirectUrls` entries are matched against the full `redirectTo` value, including scheme, host, optional port, and path.

- Exact entries must match exactly, such as `https://myapp.com/dashboard`.
- Wildcards are supported only in the host portion, such as `https://*.myapp.com/callback`.
- Deep links are allowed when explicitly listed, such as `com.example.app:/oauth2redirect` or `myapp://auth/callback`.
- If `allowedRedirectUrls` is empty, InsForge allows all redirects for developer convenience. This is insecure for production and should be avoided outside local development.

### Update Auth Configuration

Update authentication settings (admin only).

```
PUT /api/auth/config
```

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `requireEmailVerification` | boolean | No | Whether email verification is required |
| `passwordMinLength` | integer | No | Minimum password length (4-128) |
| `requireNumber` | boolean | No | Require numbers in password |
| `requireLowercase` | boolean | No | Require lowercase in password |
| `requireUppercase` | boolean | No | Require uppercase in password |
| `requireSpecialChar` | boolean | No | Require special characters in password |
| `verifyEmailMethod` | string | No | Email verification method (`code` or `link`) |
| `resetPasswordMethod` | string | No | Password reset method (`code` or `link`) |
| `allowedRedirectUrls` | array | No | List of allowed redirect URLs. Entries are matched against the full `redirectTo` value. Exact URLs must match exactly, host wildcards such as `https://*.domain.com/callback` are supported, and custom deep links such as `com.example.app:/oauth2redirect` are allowed when explicitly listed. If empty, all redirects are allowed, which is insecure for production. |

#### Example

```bash
curl -X PUT "https://your-app.insforge.app/api/auth/config" \
  -H "Authorization: Bearer admin-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "requireEmailVerification": true,
    "passwordMinLength": 10,
    "verifyEmailMethod": "link"
  }'
```

### Exchange Admin Session

Exchange a cloud provider authorization code for an admin session.

```
POST /api/auth/admin/sessions/exchange
```

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `code` | string | Yes | Authorization code or JWT from Insforge Cloud |

#### Example

```bash
curl -X POST "https://your-app.insforge.app/api/auth/admin/sessions/exchange" \
  -H "Content-Type: application/json" \
  -d '{"code": "eyJhbGciOiJIUzI1NiIs..."}'
```

#### Response

```json
{
  "admin": {
    "sub": "cloud:user_123"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "csrfToken": "abc123..."
}
```

### Get Current Admin Session

Get the current dashboard admin session from a project admin access token.

```
GET /api/auth/admin/sessions/current
```

#### Response

```json
{
  "admin": {
    "sub": "local:admin"
  }
}
```

### Refresh Admin Session

Refresh a dashboard admin access token. This endpoint uses the dashboard-only
`insforge_admin_refresh_token` httpOnly cookie and does not share the app/user
refresh cookie.

```
POST /api/auth/admin/refresh
```

```bash
curl -X POST "https://your-app.insforge.app/api/auth/admin/refresh" \
  -H "X-CSRF-Token: abc123..." \
  --cookie "insforge_admin_refresh_token=..."
```

### Logout Admin Session

```
POST /api/auth/admin/logout
```

---

## Error Responses

### Invalid Credentials (401)

```json
{
  "error": "INVALID_CREDENTIALS",
  "message": "Invalid email or password",
  "statusCode": 401,
  "nextActions": "Check your email and password"
}
```

### User Already Exists (409)

```json
{
  "error": "USER_EXISTS",
  "message": "User with this email already exists",
  "statusCode": 409,
  "nextActions": "Use a different email or sign in"
}
```

### Email Not Verified (403)

```json
{
  "error": "EMAIL_NOT_VERIFIED",
  "message": "Please verify your email before signing in",
  "statusCode": 403,
  "nextActions": "Check your inbox for verification email"
}
```
