createSessionToken

Not yet released. The packages on this page are not published to npm yet, so the install commands below will not resolve. The documented interface is stable and the code exists; only publication is outstanding. To use KeyStone from a frontend today, call the REST API or the TypeScript SDK, which is published. Contact us if you need early access.

Import

import { createSessionToken } from '@keystoneos/node';

Usage

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. Omit the property for an unrestricted token; an empty array is rejected with `422`.
`metadata`	`object`	No	-	Audit trail context (user ID, email, etc.).

Available Scopes

Scope	Description
`settlements:read`	List and view settlements and instructions, read events, fetch deposit calldata.
`settlements:write`	Submit paired instructions.
`templates:read`	List and view templates.

Any other value is rejected with 422. A session token is browser-delivered, so settlements:write does not authorize settlement creation, compliance decisions, or instruction cancellation the way it does in your M2M credential - those return 403 SESSION_WRITE_DENIED. See Authentication.

Return Type

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:

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

The token holder can only access the specified settlements: requests addressing any other settlement return 403 (SESSION_SETTLEMENT_SCOPE_DENIED), and listing endpoints filter to the permitted set. A restricted token also cannot create settlements or use the instructions endpoints, since those resources cannot belong to a list fixed at mint time - mint an unrestricted token for instruction-submitting widgets.

Overview

Backend SDKs

Frontend Library

Tools

Import

Usage

Parameters

CreateSessionTokenOptions

Available Scopes

Return Type

Scoped Tokens

​Import

​Usage

​Parameters

​CreateSessionTokenOptions

​Available Scopes

​Return Type

​Scoped Tokens

Import

Usage

Parameters

CreateSessionTokenOptions

Available Scopes

Return Type

Scoped Tokens