Server SDK

The @guidekit/server package provides server-side utilities for secure token generation and validation.

Installation


npm install @guidekit/server

`createSessionToken`

Generates a signed JWT for client authentication. API keys are stored server-side in a sessionKeyStore keyed by the token’s jti claim — they never leave the server or appear in the JWT payload. The client SDK sends this token with every request.


import { createSessionToken } from '@guidekit/server';
 
export async function POST() {
  const token = await createSessionToken({
    signingSecret: process.env.GUIDEKIT_SECRET!,
    llmApiKey: process.env.LLM_API_KEY!,
    sttApiKey: process.env.STT_API_KEY,
    ttsApiKey: process.env.TTS_API_KEY,
    expiresIn: '15m',
  });
 
  return Response.json(token);
}

Options

Option	Type	Required	Description
`signingSecret`	`string`	Yes	Secret used to sign the JWT
`llmApiKey`	`string`	No	LLM provider API key
`sttApiKey`	`string`	No	STT provider API key (for speech-to-text)
`ttsApiKey`	`string`	No	TTS provider API key (for text-to-speech)
`expiresIn`	`string`	No	Token lifetime (default: `'15m'`)
`metadata`	`object`	No	Custom claims to include in the token

`validateSessionToken`

Verifies and decodes a token. Useful for custom middleware or edge functions.


import { validateSessionToken } from '@guidekit/server';
 
const result = await validateSessionToken(
  request.headers.get('Authorization')?.replace('Bearer ', '')!,
  process.env.GUIDEKIT_SECRET!,
);
 
if (!result.valid) {
  return new Response('Unauthorized', { status: 401 });
}

Secret Rotation

To rotate your signing secret without downtime:

Generate a new secret: npx guidekit generate-secret
Set GUIDEKIT_SECRET_NEW in your environment
Update your token endpoint to sign with the new secret
Wait for all existing tokens to expire (default 15 minutes)
Remove the old secret and rename GUIDEKIT_SECRET_NEW to GUIDEKIT_SECRET

Framework Examples

Next.js App Router


// app/api/guidekit/token/route.ts
import { createSessionToken } from '@guidekit/server';
 
export async function POST() {
  const token = await createSessionToken({ /* ... */ });
  return Response.json(token);
}

Express


import express from 'express';
import { createSessionToken } from '@guidekit/server';
 
const app = express();
 
app.post('/api/guidekit/token', async (req, res) => {
  const token = await createSessionToken({ /* ... */ });
  res.json(token);
});