Authentication

The gateway supports three auth schemes. Which one to use depends on where the request originates.

Schemes at a glance

Scheme	Format	Use case
`Bearer`	OIDC JWT (Alpha)	Frontend app with a signed-in user
`GatelitSigned`	Short-lived HMAC token	Frontend app, server issues tokens per-user
`GatelitKey`	Long-lived service key	Backend scripts, server-to-server, CI

Bearer (OIDC)

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

Pass the user’s JWT from your OIDC provider directly.

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

GatelitSigned

Your backend exchanges a service key for a short-lived HMAC-signed token via the gateway’s token exchange endpoint. The token encodes the subject and optional constraints (model, org, max tokens). The gateway verifies the signature without a DB call.

Authorization: GatelitSigned eyJhbGci...

Exchange a service key for a signed token:

import { exchangeToken } from "@gatelit/sdk"

// In your API route / server action:
const { token } = await exchangeToken({
  gatewayUrl: "https://gateway.gatelit.dev",
  serviceKey: process.env.GATELIT_SERVICE_KEY!,
  sub: session.userId,        // Required — identifies the requester
  orgId: session.orgId,       // Optional — enables org-scoped provider keys
  model: "openai/gpt-4o",     // Optional — restrict to a specific model
  ttl: 60,                    // Seconds until expiry (default: 60)
})

return { token, scheme: "GatelitSigned" }

When to use: Frontend apps where you need per-user model restrictions with short-lived tokens. The short TTL means leaked tokens expire quickly.

Token exchange requires a service key created in the dashboard. No raw signing secret is ever exposed to your backend.

GatelitKey

A long-lived service key created in the dashboard.

Authorization: GatelitKey glk_abc123...

Create keys in Settings → Service Keys. Each key can optionally be scoped to a specific org. When to use: Backend-to-backend, scripts, CI pipelines, or any server-side code where managing token expiry is inconvenient.

Never use a service key in browser/frontend code. It cannot be expired quickly and has no per-request TTL.

Org-scoped provider keys

When your token includes an orgId (either via the JWT claims or a GatelitSigned token), the gateway uses that org’s provider keys configured in the dashboard. This lets each org bring their own provider keys (BYOK) while falling back to your gateway’s default keys.

How it works

API Reference

Schemes at a glance

Bearer (OIDC)

GatelitSigned

GatelitKey

Org-scoped provider keys

​Schemes at a glance

​Bearer (OIDC)

​GatelitSigned

​GatelitKey

​Org-scoped provider keys

Schemes at a glance

Bearer (OIDC)

GatelitSigned

GatelitKey

Org-scoped provider keys