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

# Handlers

> One-line Next.js and Express routes that mint AiQL embed tokens.

Use the factory helpers for a ready-made `GET` handler, or call `mintWorkspaceToken` / `handleTokenRequest` in any framework.

## Import

```ts theme={null}
import {
  createNextHandler,
  createExpressHandler,
  handleTokenRequest,
  mintWorkspaceToken,
} from "@aiql.io/react/server";
```

## Usage

### Next.js App Router

`app/api/aiql/route.ts`:

```ts theme={null}
import { createNextHandler } from "@aiql.io/react/server";

export const GET = createNextHandler();
```

### Express

```ts theme={null}
import { createExpressHandler } from "@aiql.io/react/server";

app.get("/api/aiql", createExpressHandler());
```

### With options

```ts theme={null}
export const GET = createNextHandler({
  ttlSeconds: 1800,
  // apiKey / workspaceId override env when set
});
```

### Any framework

```ts theme={null}
import { handleTokenRequest, mintWorkspaceToken } from "@aiql.io/react/server";

const { status, body } = await handleTokenRequest();
// return status + body as JSON from your route

const { token, expiresAt, expiresIn } = await mintWorkspaceToken();
```

### Successful response body

```json theme={null}
{
  "ok": true,
  "token": "<jwt>",
  "expiresIn": 1800,
  "expiresAt": "2026-07-21T12:00:00.000Z"
}
```

On failure the helpers return `ok: false` with an `error` string (HTTP 503 when credentials are missing, otherwise 502).

## API Reference

### Handler options

Shared by `createNextHandler`, `createExpressHandler`, `handleTokenRequest`, and `mintWorkspaceToken`.

| Option        | Type     | Default                         | Description                         |
| ------------- | -------- | ------------------------------- | ----------------------------------- |
| `apiKey`      | `string` | `process.env.AIQL_API_KEY`      | AiQL API key.                       |
| `workspaceId` | `string` | `process.env.AIQL_WORKSPACE_ID` | Workspace id for the token.         |
| `ttlSeconds`  | `number` | Upstream default                | Optional token lifetime override.   |
| `baseUrl`     | `string` | `"https://app.aiql.io"`         | AiQL app base URL used for minting. |

### createNextHandler

Returns an async `GET` function compatible with the Next.js App Router `Response.json` pattern.

### createExpressHandler

Returns an Express-style `(req, res) => …` handler that calls `res.status(…).json(…)`.

### handleTokenRequest

Returns `{ status, body }` so you can adapt the result to any HTTP framework.

### mintWorkspaceToken

Calls `POST {baseUrl}/api/embed/tokens` and returns `{ token, expiresIn, expiresAt }`. Throws if credentials are missing or the upstream request fails.

Pair these handlers with [`useToken`](/sdks/react/hooks/use-token) on the client.