> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gatelit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate requests to the Gatelit gateway.

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)

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

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

```http theme={null}
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.

```http theme={null}
Authorization: GatelitSigned eyJhbGci...
```

Generate tokens with the SDK:

```ts theme={null}
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.

<Info>
  `GATELIT_SIGNING_SECRET` must match the same value in both your backend and the gateway's environment.
</Info>

***

## GatelitKey

A long-lived service key created in the dashboard.

```http theme={null}
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.

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

***

## 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.