signToken

signToken creates a compact, short-lived token that your frontend can use with the "GatelitSigned" auth scheme. Call it from your backend — never from client-side code.

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

const token = await signToken(options: SignedTokenOptions, secret: string): Promise<string>

The function uses the Web Crypto API, available natively in Node.js 18+ and all edge runtimes (Cloudflare Workers, Vercel Edge, Deno). The returned string is a compact dot-separated value: base64url(header).base64url(payload).base64url(signature) — structurally identical to a standard HS256 JWT.

Never call signToken or expose GATELIT_SIGNING_SECRET in frontend code. Import @gatelit/sdk/sign only from server-side files (API routes, server functions, edge middleware).

Parameters

`options`

string

required

User identifier embedded in the token. Used for request attribution in dashboard logs.

string

Organisation ID to embed in the token. The gateway uses this to resolve org-scoped provider keys when BYOK is configured.

string

Restrict this token to a single model in "provider/model-name" format (for example "openai/gpt-4o"). Requests using a different model are rejected by the gateway. Omit to allow any model permitted by your policy.

number

Cap the maximum output tokens for requests made with this token.

number

default:"60"

Token lifetime in seconds. Defaults to 60. Tokens expire at iat + ttl.

`secret`

string

required

Your GATELIT_SIGNING_SECRET. Store this in an environment variable and never expose it outside your server.

Examples

Nuxt server route

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

export default defineEventHandler(async (event) => {
  const user = await requireUser(event) // your auth middleware
  const token = await signToken({
    sub: user.id,
    model: "openai/gpt-4o",
    maxTokens: 500,
    ttl: 60,
  }, process.env.GATELIT_SIGNING_SECRET!)
  return { token }
})

Next.js API route

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

export async function GET(req: Request) {
  // authenticate your user first — e.g. verify a session cookie
  const userId = await getUserIdFromRequest(req)
  if (!userId) {
    return Response.json({ error: "Unauthorized" }, { status: 401 })
  }

  const token = await signToken(
    {
      sub: userId,
      model: "openai/gpt-4o",
      maxTokens: 500,
      ttl: 60,
    },
    process.env.GATELIT_SIGNING_SECRET!,
  )

  return Response.json({ token })
}

import type { NextApiRequest, NextApiResponse } from "next"
import { signToken } from "@gatelit/sdk/sign"

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  // authenticate your user first
  const userId = await getUserIdFromRequest(req)
  if (!userId) {
    return res.status(401).json({ error: "Unauthorized" })
  }

  const token = await signToken(
    {
      sub: userId,
      model: "openai/gpt-4o",
      maxTokens: 500,
      ttl: 60,
    },
    process.env.GATELIT_SIGNING_SECRET!,
  )

  res.json({ token })
}

Using the token on the frontend

Once your backend endpoint issues a token, pass it to GatelitClient via getToken:

import { GatelitClient } from "@gatelit/sdk"

const client = new GatelitClient({
  gatewayUrl: "https://gateway.yourapp.com",
  getToken: async () => {
    const { token } = await fetch("/api/ai-token").then(r => r.json())
    return { token, scheme: "GatelitSigned" }
  },
})

getToken is called before every request. If your users make several requests in quick succession, consider caching the token in a variable and only re-fetching a new one when the current token is within a few seconds of expiry.

Security notes

Never import @gatelit/sdk/sign in browser code. The separate import path exists specifically to prevent the signing code from being bundled into client builds.
Store the secret in an environment variable. Use process.env.GATELIT_SIGNING_SECRET (or your runtime’s equivalent) and ensure it is excluded from version control.
Authenticate the user before issuing a token. signToken does not perform any authentication — you must verify the caller’s identity in your own middleware before calling it.
Keep TTLs short. The default of 60 seconds is appropriate for most use cases. A shorter TTL limits the window of exposure if a token is intercepted.

JavaScript SDK

Vue SDK

Gateway API

Parameters

`options`

`secret`

Examples

Nuxt server route

Next.js API route

Using the token on the frontend

Security notes

​Parameters

​options

​secret

​Examples

​Nuxt server route

​Next.js API route

​Using the token on the frontend

​Security notes

Parameters

`options`

`secret`

Examples

Nuxt server route

Next.js API route

Using the token on the frontend

Security notes