# AI Gateway Setup

> Connect OpenAI, Anthropic, OpenRouter or AWS Bedrock to the ZopNight AI Gateway. Lists the exact key type or AWS access each provider needs, and how your developers point their tools at the gateway.

Source: https://zop.dev/developer-docs/integrations/ai-gateway

---

The **AI Gateway** sits between your developers and your AI providers. You connect a provider once.
Your developers then use a ZopNight **virtual key** instead of the provider key. Each virtual key
has its own budget and list of allowed models, and every request shows up in AI spend reports.

## Before you start

| Need | Detail |
|---|---|
| A ZopNight **Admin** | Only Admins connect providers and manage models. Editors create virtual keys. |
| A provider account | OpenAI, Anthropic, OpenRouter, or an AWS account with Bedrock. |
| For Bedrock: a connected AWS account | Connected under [Cloud Accounts](https://zop.dev/docs/cloud-setup/cloud-accounts) with **read and write** access. |
| Outbound HTTPS for your developers | Their tools call `https://api.zop.dev/ai-gateway`. Nothing calls into your network. |

## Access to grant

### OpenAI, Anthropic and OpenRouter

Each provider needs one API key. Before saving it, ZopNight makes one read call with the key, and
rejects a key the provider refuses.

| Provider | Key to create | Minimum access |
|---|---|---|
| OpenAI | A project API key | All, or Restricted with the two permissions below |
| Anthropic | A standard API key | A normal key from the Claude Console |
| OpenRouter | A standard API key | A normal key |

For an OpenAI **Restricted** key, turn on these two, as named in
[OpenAI's permission list](https://developers.openai.com/api/docs/guides/rbac):

- **List models:** *Read*. Without it the key is rejected when you connect.
- **Model capabilities:** *Request*. This is what lets the gateway call chat completions.

For Anthropic, use a normal API key. An Admin key (`sk-ant-admin…`) is for the
[Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api-keys), not for calling
models.

The connect check calls:

- OpenAI: `GET /v1/models`
- Anthropic: `GET /v1/models` ([List Models](https://platform.claude.com/docs/en/api/models/list))
- OpenRouter: `GET /api/v1/key` ([Get current key](https://openrouter.ai/docs/api-reference/limits))

The key is stored encrypted. It is never shown again in ZopNight or sent to your developers.

### AWS Bedrock

Bedrock needs no key. ZopNight uses the role it already has in your connected AWS account. It gets
short-lived AWS credentials from that role and refreshes them before they expire.

| IAM action | Why | Granted on |
|---|---|---|
| `bedrock:ListFoundationModels` | Find usable models | Every connection |
| `bedrock:ListInferenceProfiles` | Find cross-region IDs | Every connection |
| `bedrock:InvokeModel` | Call a model | **Read and write** only |

The list actions are in the ZopNight role's read policy. `InvokeModel` is in its write policy.

Action names are from
[Actions, resources, and condition keys for Amazon Bedrock](https://docs.aws.amazon.com/service-authorization/latest/reference/list_bedrock.html).

**Warning**

With a read-only connection, Bedrock shows as connected and its models are listed, but every request
is refused. Upgrade the AWS connection to read and write first.

**Warning**

[Streaming calls need `bedrock:InvokeModelWithResponseStream`](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html).
Tools such as Claude Code always stream. The ZopNight role does not include this action today, so
add it to the role yourself if your developers stream.

You also need the models available in your AWS account. See
[Access Amazon Bedrock foundation models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html):

- **Amazon Nova** models work as soon as Bedrock is available in your account.
- **Anthropic Claude** models need the one-time First Time Use form first. The first call to a
  third-party model also starts an AWS Marketplace subscription. The role making that first call
  needs `aws-marketplace:Subscribe`, `aws-marketplace:Unsubscribe` and
  `aws-marketplace:ViewSubscriptions`. The ZopNight role has none of these, so let someone with
  those rights make the first call.
- ZopNight's default models use cross-region IDs (`us.`, `eu.` or `apac.`, based on your region).
  Models you add under **Manage models** can also be `global.` profiles. These
  [need access to the model in every Region of the profile](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-prereq.html).
  If a Service Control Policy blocks some of those Regions, requests fail.

## Set it up

**Connect a provider**

Open **Settings → Integrations → AI Providers** and click **Connect** on the provider tile. Enter
the API key. For Bedrock, pick the **AWS account** and the **Region** instead. Click **Connect**.
ZopNight checks the key and adds a default set of models. The toast says how many were added.

**Add or remove models (optional)**

For OpenRouter and Bedrock, open the tile menu and choose **Manage models**. Add a model by picking
it from the list or entering its ID.

**Create a virtual key**

Open **AI Estate → Inference Keys** and click **Create virtual key**. Give it a name, the models it
may use, and a budget. The key is shown **once**. Copy it.

**Point your tools at the gateway**

Use the gateway address and the virtual key in place of the provider's. The key screen shows
ready-made snippets for Claude Code, the OpenAI SDK and cURL.

```bash title="Claude Code"
export ANTHROPIC_BASE_URL=https://api.zop.dev/ai-gateway
export ANTHROPIC_AUTH_TOKEN=<your virtual key>
export ANTHROPIC_MODEL=<a model name from the key>
export ANTHROPIC_DEFAULT_HAIKU_MODEL=<the same model name>
claude
```

```python title="OpenAI SDK"
from openai import OpenAI

client = OpenAI(base_url="https://api.zop.dev/ai-gateway", api_key="<your virtual key>")
```

Spend appears under **AI Estate → AI Gateway**.

## Disconnect and remove access

**Settings → Integrations → AI Providers → Disconnect** removes the provider, its models, and the
stored key or AWS credentials from ZopNight.

- Virtual keys stay, but requests to the removed models fail.
- ZopNight does not revoke anything at the provider. Delete the API key in the provider's console.
- For Bedrock, the short-lived AWS credentials expire within an hour.

## Troubleshooting

| Problem | Cause and fix |
|---|---|
| `<provider> rejected this API key`, e.g. `OpenAI rejected this API key` | For an OpenAI Restricted key, turn on **List models**. For Anthropic, use a normal API key. |
| Bedrock requests return access denied | The AWS connection is read-only, or the request streams. See the warnings above. |
| Claude on Bedrock fails on first use | Complete the First Time Use form and the Marketplace subscription in AWS. |
| **Connect** is greyed out | You need the Admin role. Ask an Admin to connect the provider. |