signToken

import { signToken } from "@gatelit/sdk/sign"

signToken creates an HMAC-SHA256 signed JWT for the GatelitSigned auth scheme. It runs on your backend using the Web Crypto API — available natively in Node.js 18+, Bun, Deno, and all edge runtimes (Cloudflare Workers, Vercel Edge).

Import from @gatelit/sdk/sign (not @gatelit/sdk) to tree-shake the rest of the SDK. The /sign subpath export only includes signToken and its dependencies.

Signature

function signToken(
  options: SignedTokenOptions,
  secret: string,
): Promise<string>

Returns a dot-separated token string: header.payload.signature.

Options

Field	Type	Required	Default	Description
`sub`	`string`	Yes	—	Subject identifier — typically the user ID
`orgId`	`string`	No	—	Org ID for org-scoped provider key resolution
`model`	`string`	No	—	Restrict to one model in `provider/model` format
`maxTokens`	`number`	No	—	Cap output tokens per request
`ttl`	`number`	No	`60`	Token lifetime in seconds
`endUserId`	`string`	No	—	End-user ID for log filtering
`requestSource`	`"api" \| "dashboard" \| "eval"`	No	—	Tag for request source filtering

Examples

Minimal — user identity only

await signToken({ sub: "user_123" }, process.env.GATELIT_SIGNING_SECRET!)

Constrained — specific model with a token cap

await signToken(
  {
    sub: "user_123",
    orgId: "org_456",
    model: "openai/gpt-4o",
    maxTokens: 500,
    ttl: 30,
  },
  process.env.GATELIT_SIGNING_SECRET!,
)

Full — end-user tracking with request source

await signToken(
  {
    sub: "user_123",
    orgId: "org_456",
    model: "anthropic/claude-3-5-haiku-20241022",
    maxTokens: 1000,
    ttl: 60,
    endUserId: "customer_789",
    requestSource: "api",
  },
  process.env.GATELIT_SIGNING_SECRET!,
)

Nuxt server route

// server/api/ai-token.get.ts
import { signToken } from "@gatelit/sdk/sign"

export default defineEventHandler(async (event) => {
  const { user } = await requireUserSession(event)
  if (!user) throw createError({ statusCode: 401 })

  const token = await signToken(
    {
      sub: user.id,
      orgId: user.orgId,
      model: "openai/gpt-4o",
    },
    useRuntimeConfig().gatewaySigningSecret,
  )
  return { token }
})

Next.js API route

// app/api/ai-token/route.ts
import { signToken } from "@gatelit/sdk/sign"

export async function GET() {
  const token = await signToken(
    { sub: "user_123", model: "openai/gpt-4o", ttl: 60 },
    process.env.GATELIT_SIGNING_SECRET!,
  )
  return Response.json({ token })
}

Express route

import { signToken } from "@gatelit/sdk/sign"

app.get("/api/ai-token", async (req, res) => {
  const token = await signToken(
    { sub: req.user!.id, model: "openai/gpt-4o-mini" },
    process.env.GATELIT_SIGNING_SECRET!,
  )
  res.json({ token })
})

Token structure

The signed token embeds the following JWT claims the gateway reads:

iat — Issued at (epoch seconds)
exp — Expires at (iat + ttl)
sub — Subject (user ID)
orgId — (optional) Organisation context
policyOverride — (optional) Encoded model restriction and token cap
endUserId — (optional) End-user identifier
requestSource — (optional) api | dashboard | eval

The gateway verifies the HMAC signature without a database call — fast, stateless, and cache-friendly.

TypeScript

TypeScript Reference

Vue

Signature

Options

Examples

Minimal — user identity only

Constrained — specific model with a token cap

Full — end-user tracking with request source

Nuxt server route

Next.js API route

Express route

Token structure

​Signature

​Options

​Examples

​Minimal — user identity only

​Constrained — specific model with a token cap

​Full — end-user tracking with request source

​Nuxt server route

​Next.js API route

​Express route

​Token structure

Signature

Options

Examples

Minimal — user identity only

Constrained — specific model with a token cap

Full — end-user tracking with request source

Nuxt server route

Next.js API route

Express route

Token structure