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

# createSessionToken

> Create a scoped session token for frontend use.

## Import

```typescript theme={null}
import { createSessionToken } from '@keystoneos/node';
```

## Usage

```typescript theme={null}
import { KeystoneClient } from '@keystoneos/sdk';
import { createSessionToken } from '@keystoneos/node';

const keystone = new KeystoneClient({
  clientId: process.env.KEYSTONE_CLIENT_ID,
  clientSecret: process.env.KEYSTONE_CLIENT_SECRET,
  environment: 'production',
});

// In your API route handler
app.post('/api/keystone/session', async (req, res) => {
  const session = await createSessionToken(keystone, {
    scopes: ['settlements:read', 'settlements:write'],
    metadata: { userId: req.user.id, email: req.user.email },
  });

  res.json({ token: session.sessionToken, expiresAt: session.expiresAt });
});
```

## Parameters

| Parameter | Type                        | Required | Description                                       |
| --------- | --------------------------- | -------- | ------------------------------------------------- |
| `client`  | `object`                    | Yes      | A configured KeystoneClient or compatible object. |
| `options` | `CreateSessionTokenOptions` | Yes      | Token configuration.                              |

### CreateSessionTokenOptions

| Property        | Type       | Required | Default | Description                                 |
| --------------- | ---------- | -------- | ------- | ------------------------------------------- |
| `scopes`        | `string[]` | Yes      | -       | Permissions for the token.                  |
| `expiresIn`     | `number`   | No       | `3600`  | TTL in seconds (60 to 86400).               |
| `settlementIds` | `string[]` | No       | -       | Restrict to specific settlements.           |
| `metadata`      | `object`   | No       | -       | Audit trail context (user ID, email, etc.). |

### Available Scopes

| Scope                | Description                               |
| -------------------- | ----------------------------------------- |
| `settlements:read`   | List and view settlements.                |
| `settlements:write`  | Create settlements, compliance decisions. |
| `templates:read`     | List and view templates.                  |
| `instructions:read`  | List and view instructions.               |
| `instructions:write` | Submit and cancel instructions.           |

## Return Type

```typescript theme={null}
interface SessionTokenResponse {
  sessionToken: string;  // The JWT to pass to KeystoneProvider
  expiresAt: string;     // ISO 8601 expiry timestamp
  tokenId: string;       // Token ID for revocation
}
```

## Scoped Tokens

Restrict a token to specific settlement IDs for least-privilege access:

```typescript theme={null}
const session = await createSessionToken(keystone, {
  scopes: ['settlements:read'],
  settlementIds: [settlementId],
  metadata: { userId: req.user.id },
});
```

The token holder can only access the specified settlements. Other settlement requests return 403.