> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insforge.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication API Reference

> REST endpoints for user sign-up, password and email OTP sign-in, email verification, password reset, OAuth, and session management.

## Overview

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

## Headers

For authenticated function invocations:

```bash theme={null}
Authorization: Bearer your-jwt-token-or-anon-key
Content-Type: application/json
```

For admin endpoints:

```bash theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
{
  "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 theme={null}
{
  "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                                                                    |
| ---------- | ------ | ------------ | ------------------------------------------------------------------------------ |
| `method`   | string | No           | Authentication method. Defaults to `password`; use `otp` for email OTP sign-in |
| `email`    | string | Yes          | User email address                                                             |
| `password` | string | For password | User password                                                                  |

### Example (Web Client)

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

### Example (Non-Web Client)

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

### Response (Web Client)

```json theme={null}
{
  "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 theme={null}
{
  "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>

***

## Email OTP Sign In

Use this passwordless flow when a user should sign in with a 6-digit code sent to their email address.

### Send a Sign-In Code

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

#### Request Body

| Field   | Type   | Required | Description                                  |
| ------- | ------ | -------- | -------------------------------------------- |
| `email` | string | Yes      | Email address that receives the sign-in code |

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

The endpoint returns `202 Accepted` with a generic message. It does not reveal whether the email already belongs to a user.

### Create a Session with the Code

```
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                                               |
| -------- | ------ | -------- | --------------------------------------------------------- |
| `method` | string | Yes      | Must be `otp`                                             |
| `email`  | string | Yes      | Email address that received the code                      |
| `otp`    | string | Yes      | 6-digit sign-in code                                      |
| `name`   | string | No       | Profile name used only if verification creates a new user |

```bash theme={null}
curl -X POST "https://your-app.insforge.app/api/auth/sessions?client_type=server" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "otp",
    "email": "user@example.com",
    "otp": "123456",
    "name": "Ada Lovelace"
  }'
```

The response uses the same session shape and `client_type` behavior as password sign-in.

<Note>
  * Codes expire after 5 minutes, can be used once, and are consumed after three failed attempts.
  * InsForge does not create a user when the code is sent. If the email is new, a verified passwordless user is created only after successful verification.
  * Verifying a code for an existing unverified account clears its stored password, leaving the account passwordless.
  * If public signups are disabled, an existing user can still sign in. A valid code for an unknown email is consumed and returns HTTP 403.
</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 theme={null}
curl -X POST "https://your-app.insforge.app/api/auth/refresh" \
  -H "X-CSRF-Token: abc123..." \
  --cookie "refresh_token=..."
```

### Example (Non-Web Client)

```bash theme={null}
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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
curl -X POST "https://your-app.insforge.app/api/auth/logout"
```

### Response

```json theme={null}
{
  "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 theme={null}
curl "https://your-app.insforge.app/api/auth/sessions/current" \
  -H "Authorization: Bearer your-jwt-token"
```

### Response

```json theme={null}
{
  "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 theme={null}
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 theme={null}
{
  "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 theme={null}
curl "https://your-app.insforge.app/api/auth/profiles/123e4567-e89b-12d3-a456-426614174000"
```

### Response

```json theme={null}
{
  "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 theme={null}
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 theme={null}
{
  "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 theme={null}
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 theme={null}
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 theme={null}
{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "csrfToken": "abc123..."
}
```

### Response (Non-Web Client)

```json theme={null}
{
  "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 theme={null}
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 theme={null}
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 theme={null}
{
  "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 theme={null}
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 theme={null}
{
  "message": "Password reset successfully"
}
```

***

## Native ID Token Sign-In

Exchange an ID token from Google or Apple's native AuthenticationServices framework for an
InsForge session:

```
POST /api/auth/id-token?client_type=mobile
```

### Query Parameters

| Parameter     | Type                                       | Required | Description                                                                                                |
| ------------- | ------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| `client_type` | `web` \| `mobile` \| `desktop` \| `server` | No       | Defaults to `web`. Controls whether the refresh token is set as a cookie or returned in the response body. |

### Request Body

| Field      | Type                | Required   | Description                                                                                                           |
| ---------- | ------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- |
| `provider` | `google` \| `apple` | Yes        | Native identity provider that issued the token.                                                                       |
| `token`    | string              | Yes        | Raw provider ID token. For Apple, use `identityToken` from `ASAuthorizationAppleIDCredential`.                        |
| `nonce`    | string              | Apple only | Original raw nonce, 1–255 characters. It is hashed without normalization and must match Apple's signed `nonce` claim. |
| `name`     | string              | No         | Apple first-authorization display name, 1–100 characters. Apple may only provide this value once.                     |

For native Sign in with Apple, generate a high-entropy raw nonce and attach its lowercase
SHA-256 hex digest to the `ASAuthorizationAppleIDRequest`. Send the original raw nonce with the
returned identity token. InsForge hashes it before comparing it with Apple's signed `nonce`
claim. If Apple returns a name on first authorization, send the display name in the same request;
later authorizations may omit it.

```bash theme={null}
curl -X POST "https://your-app.insforge.app/api/auth/id-token?client_type=mobile" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "apple",
    "token": "APPLE_IDENTITY_TOKEN",
    "nonce": "ORIGINAL_RAW_NONCE",
    "name": "Optional First Sign-In Name"
  }'
```

InsForge verifies Apple's signature, issuer, expiry, subject, nonce, and token audience. The
audience is selected exclusively from the project's Apple OAuth configuration; the sign-in
request cannot override it. Configure the native App ID (normally the iOS bundle identifier) in
`nativeClientIds` while retaining `clientId` for the browser/service OAuth client when needed:

```bash theme={null}
curl -X PUT "https://your-app.insforge.app/api/auth/oauth/apple/config" \
  -H "Authorization: Bearer ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nativeClientIds": ["com.example.ios-app"]
  }'
```

Apple private-relay addresses are supported. InsForge finds returning accounts by Apple's stable
subject before inspecting profile claims, so a returning user can sign in when optional profile
data is absent. Creating or email-linking a new account requires a verified email from the Apple
identity token; InsForge never creates a fabricated placeholder address.

Google keeps its existing request shape:

```json theme={null}
{
  "provider": "google",
  "token": "GOOGLE_ID_TOKEN"
}
```

### Response

| Field          | Type   | Description                                                                                                             |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `user`         | object | Authenticated InsForge user, including `id`, `email`, verification state, providers, profile, metadata, and timestamps. |
| `accessToken`  | string | InsForge access token for authenticated API requests.                                                                   |
| `refreshToken` | string | Returned for `mobile`, `desktop`, and `server` clients. Omitted for web clients.                                        |
| `csrfToken`    | string | Returned for web clients alongside the HTTP-only refresh-token cookie.                                                  |

```json theme={null}
{
  "user": {
    "id": "00000000-0000-4000-8000-000000000001",
    "email": "user@example.com",
    "emailVerified": true,
    "providers": ["apple"]
  },
  "accessToken": "INSFORGE_ACCESS_TOKEN",
  "refreshToken": "INSFORGE_REFRESH_TOKEN"
}
```

### Errors

| Status | Meaning                                                                                                         |
| ------ | --------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid request shape, unsupported provider, missing nonce, or missing verified email for a new Apple identity. |
| `401`  | Provider token is invalid, expired, has an untrusted audience, or fails Apple nonce verification.               |
| `429`  | Too many ID-token sign-in attempts from the requesting IP.                                                      |

For `client_type=mobile`, `desktop`, or `server`, the response includes `refreshToken` in the
JSON body. Web clients receive the refresh token in an HTTP-only cookie and a `csrfToken` in the
response body.

***

## 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 theme={null}
# 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 theme={null}
# 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 theme={null}
{
  "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 theme={null}
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 theme={null}
{
  "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 theme={null}
// 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 theme={null}
curl "https://your-app.insforge.app/api/auth/public-config"
```

### Response

```json theme={null}
{
  "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 theme={null}
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 theme={null}
curl "https://your-app.insforge.app/api/auth/config" \
  -H "Authorization: Bearer admin-jwt-token"
```

#### Response

```json theme={null}
{
  "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 theme={null}
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 theme={null}
curl -X POST "https://your-app.insforge.app/api/auth/admin/sessions/exchange" \
  -H "Content-Type: application/json" \
  -d '{"code": "eyJhbGciOiJIUzI1NiIs..."}'
```

#### Response

```json theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
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 theme={null}
{
  "error": "INVALID_CREDENTIALS",
  "message": "Invalid email or password",
  "statusCode": 401,
  "nextActions": "Check your email and password"
}
```

### User Already Exists (409)

```json theme={null}
{
  "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 theme={null}
{
  "error": "EMAIL_NOT_VERIFIED",
  "message": "Please verify your email before signing in",
  "statusCode": 403,
  "nextActions": "Check your inbox for verification email"
}
```