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 issues a short-lived HMAC-signed token. The token encodes the subject and optional constraints (model, org, max tokens). The gateway verifies the signature without a DB call.

Authorization: GatelitSigned eyJhbGci...

Generate tokens with the SDK:

import { signToken } from "@gatelit/sdk"

// In your API route / server action:
const token = await signToken(
  {
    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)
  },
  process.env.GATELIT_SIGNING_SECRET!
)

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.

GATELIT_SIGNING_SECRET must match the same value in both your backend and the gateway’s environment.

GatelitKey

A long-lived service key created in the dashboard.

Authorization: GatelitKey sk_live_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