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

# Service Keys (GatelitKey)

> Long-lived keys for backend services, agents, and automated pipelines where there is no end user.

Service keys are long-lived credentials that you create from the Gatelit dashboard. They are designed for server-side callers — backend services, scheduled jobs, AI agents, or any automated pipeline that calls the gateway without a human user present.

<Warning>
  Treat service keys like passwords. Anyone who holds a key can make requests through your gateway. Never expose service keys in frontend code, commit them to source control, or include them in client-side bundles.
</Warning>

## Creating a key

1. Open the Gatelit dashboard and navigate to **Settings → Service Keys**.
2. Click **New key**, give it a descriptive name (e.g. `data-pipeline-prod`), and confirm.
3. Copy the key immediately — it is only shown once.
4. Store it in your environment's secret manager (e.g. as an environment variable or a secrets vault entry).

## Using a service key

### With GatelitClient

Pass the key in `getToken` with `scheme: "GatelitKey"`:

```ts theme={null}
import { GatelitClient } from "@gatelit/sdk"

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

const response = await client.chat({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Summarize the following document." }],
})

console.log(response.content)
```

### Direct HTTP request

If you're calling the gateway without the SDK, set the `Authorization` header manually:

```ts theme={null}
const response = await fetch("https://gateway.yourapp.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `GatelitKey ${process.env.GATELIT_SERVICE_KEY}`,
  },
  body: JSON.stringify({
    model: "anthropic/claude-3-5-sonnet-20241022",
    messages: [{ role: "user", content: "Hello from the backend." }],
  }),
})
```

### Shell / cURL

```bash theme={null}
curl https://gateway.yourapp.com/v1/chat/completions \
  -H "Authorization: GatelitKey $GATELIT_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'
```

## Key rotation

You should rotate service keys periodically or immediately if a key is suspected to have been exposed.

<Steps>
  <Step title="Create a new key">
    In the dashboard, go to **Settings → Service Keys** and create a new key. Give it a distinct name so you can track which services use it.
  </Step>

  <Step title="Deploy the new key">
    Update the environment variable or secret store entry in your service to use the new key value. Deploy your service.
  </Step>

  <Step title="Revoke the old key">
    Once your service is running with the new key and all in-flight requests using the old key have completed, return to the dashboard and revoke the old key.
  </Step>
</Steps>

<Tip>
  Keep one key per service or pipeline rather than sharing a single key across multiple callers. This makes rotation and incident response straightforward — you can revoke a compromised key without affecting unrelated services.
</Tip>