# Create an API key

An API key is a credential for an automation or for code. The client sends it as a bearer token on every call. Use a key for n8n, the Claude Messages API, REST calls and scripts. For a person who uses a chat or coding client, [create a gateway user](https://docs.faustine.ai/agent-gateway/gateway-users/) instead.

A key belongs to the environment it was created in. On any other environment it is refused like a key that does not exist.

## Create a key

To create an API key:

1. In the portal, go to [**Agent Gateway**](https://auth.faustine.ai/go?to=%2Fintegrations%2Fagent-gateway) and select your gateway.
2. Check the environment button in the header. The key will work on the environment it names.
3. Select the **Access** tab, then **API keys**, then **Create key**.
4. Under **Name**, enter who or what uses the key, such as `n8n prod`. The name identifies the key in Logs and in Topology. Select **Continue**.
5. Under **Scope**, leave **Everything (\*)** or select the operations the key can call. To refuse every write, turn on **Read-only**. Select **Continue**.
6. Under **Behavior**, choose what the key does with operations that require confirmation. A new key starts on **Refuse**. Select **Continue**.
7. Under **Limits**, set limits lower than the environment's, or leave the fields empty to use the environment's.
8. Select **Create key**.

A dialog shows the key once. It starts with `fik_`. Copy it and store it in your secret manager. Faustine keeps only a hash and cannot show the key again.

![The Access tab with one API key, its scopes, its calls this month and its state.](https://docs.faustine.ai/images/agent-gateway/access-light.png)

## Use the key

Send the key in the `Authorization` header. `<GATEWAY_KEY>` is the key you copied.

```bash
curl https://gateway.faustine.ai/<workspace>/<gateway>/openapi.json \
  -H "Authorization: Bearer <GATEWAY_KEY>"
```

The gateway's **Connect** tab has a snippet for each client with your URL filled in. See [Connect clients](https://docs.faustine.ai/agent-gateway/connect-clients/).

## Rotate a key

Rotating issues a new key and keeps the old one working for a grace period, so you can deploy the new key before the old one stops.

To rotate a key:

1. In **Access** > **API keys**, select the key.
2. Select **Rotate**.
3. Enter the **Grace period (hours)**. With `0`, the current key is revoked immediately.
4. Confirm, and copy the new key from the dialog.

## Revoke a key

Select the key, then **Revoke**. Clients that use the key are rejected immediately. A revoked key cannot be restored.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `401` with `Invalid API key` | The key belongs to another environment or another gateway, or was mistyped. | Use the URL of the environment the key was created in. |
| `401` with `API key revoked` | The key was revoked. | Create a new key. |
| `401` with `API key rotated and its grace period has ended` | The client still sends the key that was rotated out. | Deploy the new key. |
| `403` with `requires_confirmation` | The operation requires confirmation and the key is set to **Refuse**. | See [Set how a credential confirms writes](https://docs.faustine.ai/agent-gateway/set-confirmation/). |

## Next steps

- [Scope a key or user](https://docs.faustine.ai/agent-gateway/scope-a-credential/): narrow what a key can call.
- [Limits and quotas](https://docs.faustine.ai/agent-gateway/limits/): what each limit does and its default.
- [Call a gateway over REST and OpenAPI](https://docs.faustine.ai/technologies/rest/): call operations with the key.
- [Gateway HTTP](https://docs.faustine.ai/reference/gateway-http/): headers, response shape and errors.