Your First Request

This guide walks you through everything you need to go from zero to a working AI response using the Gatelit gateway.

Install the SDK

Install @gatelit/sdk in your project:

npm install @gatelit/sdk

The SDK is ESM-first and ships TypeScript types. It works in browsers, Node.js 18+, and edge runtimes (Cloudflare Workers, Vercel Edge, etc.).

Issue signed tokens from your backend

Gatelit uses short-lived signed tokens to authenticate client requests. Your backend signs each token with your GATELIT_SIGNING_SECRET — the token is never stored, and expires after a configurable TTL (default: 60 seconds).Import signToken from @gatelit/sdk/sign in a server-side handler:

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

export async function GET(request: Request) {
  // Validate your session here — e.g. via NextAuth, Clerk, etc.
  const userId = "user_abc123"

  const token = await signToken(
    {
      sub: userId,
      ttl: 60, // token valid for 60 seconds
    },
    process.env.GATELIT_SIGNING_SECRET!,
  )

  return Response.json({ token })
}

// 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,
      ttl: 60,
    },
    process.env.GATELIT_SIGNING_SECRET!,
  )

  return { token }
})

// routes/ai-token.ts
import { signToken } from "@gatelit/sdk/sign"
import { Router } from "express"

const router = Router()

router.get("/ai-token", async (req, res) => {
  // Validate your session here
  const userId = req.user.id

  const token = await signToken(
    {
      sub: userId,
      ttl: 60,
    },
    process.env.GATELIT_SIGNING_SECRET!,
  )

  res.json({ token })
})

The signToken function uses the Web Crypto API (available natively in Node 18+ and all edge runtimes) and returns a compact dot-separated string you pass directly to the client.

You can restrict a token to a specific model, cap its output tokens, and embed an org ID for provider key resolution. See the SignedTokenOptions type for the full set of options.

Create a GatelitClient

On the client side, instantiate GatelitClient with your gateway URL and a getToken function that fetches a fresh token from your backend endpoint:

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. You should add token caching in your implementation to avoid an extra round-trip on every request.

Send your first chat request

Call client.chat() with a model in provider/model-name format and an array of messages:

const response = await client.chat({
  model: "openai/gpt-4o-mini",
  messages: [
    { role: "user", content: "What is the Gatelit gateway?" },
  ],
})

console.log(response.content)

Supported model formats:

Provider	Example model string
OpenAI	`openai/gpt-4o-mini`
Anthropic	`anthropic/claude-3-5-sonnet-20241022`
Google	`google/gemini-2.0-flash-001`
Mistral	`mistral/mistral-small-latest`

Handle the response

client.chat() returns a ChatResponse with the following shape:

interface ChatResponse {
  /** The assistant's response text */
  content: string
  /** Resolved model identifier in "provider/model-name" format */
  model: string
  /** Token usage for this request */
  usage: {
    inputTokens: number
    outputTokens: number
    totalTokens: number
  } | null
  /** Reason the model stopped generating — e.g. "stop", "length" */
  finishReason: string | null
  /** Gatelit-specific metadata */
  meta: {
    /** Use this ID to look up the request in the Gatelit dashboard */
    requestId: string
    /** The model that actually handled the request (may differ from requested if a fallback triggered) */
    model: string
  }
}

A complete example:

const response = await client.chat({
  model: "openai/gpt-4o-mini",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Explain recursion in one sentence." },
  ],
  maxTokens: 200,
})

console.log(response.content)
// → "Recursion is when a function calls itself..."

console.log(response.usage?.totalTokens)
// → 42

console.log(response.meta.requestId)
// → "req_01j..."

Every response includes an x-gatelit-request-id response header that matches response.meta.requestId. You can paste this ID into the Gatelit dashboard to look up the full request log, including token usage, latency, and model routing details.

Get Started

Authentication

Guides

Dashboard

Your First Request