Authentication

The SDK’s GatelitClient calls getToken() before every request. What that function returns determines how the gateway identifies and authorizes the request. Three schemes are available — pick the right one for your deployment.

Service keys (`GatelitKey`)

Long-lived keys for backend use. Create them in the dashboard under Settings → Service Keys.

const client = new GatelitClient({
  gatewayUrl: "https://gateway.gatelit.dev",
  getToken: async () => ({
    token: process.env.GATELIT_SERVICE_KEY!,
    scheme: "GatelitKey",
  }),
})

Pros: Simple. No token lifecycle management. Cons: Long-lived. Revocation requires deleting the key. When: Server-side scripts, CI, cron jobs, or any backend where managing short-lived tokens is overhead.

Never use GatelitKey in browser code. It’s a long-lived secret — anyone who extracts it can make requests indefinitely.

Signed tokens (`GatelitSigned`)

Your backend exchanges a service key for a short-lived HMAC-signed JWT. The gateway verifies it without a database call. Backend — exchange a service key for a signed token:

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

export default defineEventHandler(async (event) => {
  const session = await requireAuth(event)
  const { token } = await exchangeToken({
    gatewayUrl: "https://gateway.gatelit.dev",
    serviceKey: process.env.GATELIT_SERVICE_KEY!,
    sub: session.userId,
    orgId: session.orgId,
    model: "openai/gpt-4o",      // optional — restrict model
    maxTokens: 2000,              // optional — cap output
    ttl: 60,                      // seconds (default: 60)
    endUserId: session.userId,    // optional — appears in logs
  })
  return { token }
})

Frontend — fetch the token before each request:

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

Pros: Short-lived (60s default). Encodes per-user constraints. No DB hit for verification. Cons: Requires a backend endpoint to issue tokens. When: Frontend apps with authenticated users. This is the recommended pattern for production browser apps.

OIDC tokens (`Bearer`)

OIDC authentication is in Alpha. Full self-serve configuration is coming soon. Contact us if you need OIDC support today.

Pass the user’s existing OIDC JWT directly:

const client = new GatelitClient({
  gatewayUrl: "https://gateway.gatelit.dev",
  getToken: async () => ({
    token: await supabase.auth.getSession().then(s => s.data.session?.access_token),
    scheme: "Bearer",
  }),
})

Caching tokens

getToken is called before every request. Add caching to avoid unnecessary work:

let cachedToken: { token: string; scheme: TokenScheme } | null = null
let cachedAt = 0

const client = new GatelitClient({
  gatewayUrl: "https://gateway.gatelit.dev",
  getToken: async () => {
    const now = Date.now()
    if (cachedToken && now - cachedAt < 50_000) return cachedToken

    const res = await fetch("/api/ai-token")
    const { token } = await res.json()
    cachedToken = { token, scheme: "GatelitSigned" }
    cachedAt = now
    return cachedToken
  },
})

For signed tokens with a 60-second TTL, refresh the cache slightly before expiry.

TypeScript

TypeScript Reference

Vue

Service keys (`GatelitKey`)

Signed tokens (`GatelitSigned`)

OIDC tokens (`Bearer`)

Caching tokens

​Service keys (GatelitKey)

​Signed tokens (GatelitSigned)

​OIDC tokens (Bearer)

​Caching tokens

Service keys (`GatelitKey`)

Signed tokens (`GatelitSigned`)

OIDC tokens (`Bearer`)

Caching tokens