# Anthropic

> Connect the Anthropic API to ACOG with an API key, or keyless with Anthropic workload identity federation so no key is stored anywhere.

Product: AI Cost Optimizer Gateway (ACOG). Web version: https://tessarac.com/docs/acog/providers/anthropic. Last updated: 2026-10-16.

A Direct Anthropic connection sends requests to the Anthropic API (`https://api.anthropic.com`) with your organization's own Anthropic account. It can authenticate in two ways:

| Method | What ACOG stores | Best for |
|---|---|---|
| **API key** | Your Anthropic API key, encrypted | Getting started quickly |
| **Keyless (workload identity)** | Four identifiers, no secret | Production: nothing to rotate or leak |

Claude models on Google Vertex AI or AWS Bedrock are separate connections; see [Google Vertex AI](https://tessarac.com/docs/acog/providers/google-vertex-ai.md) and [AWS Bedrock](https://tessarac.com/docs/acog/providers/aws-bedrock.md).

## Connect with an API key

1. In the [Claude Console](https://platform.claude.com/settings/keys), create an API key in the workspace whose limits and billing you want ACOG's traffic to use.
2. In ACOG, open **Admin → Providers → Connect provider**, choose **Direct** and **Anthropic**, and select **API key**.
3. Paste the key and save. ACOG lists the models the key can call; choose the ones to declare and a default model.

To rotate the key, create a new one in the Claude Console, paste it into the connection and save, then delete the old key.

## Connect keyless

A keyless connection uses [Anthropic workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation). Your Anthropic organization trusts an identity issuer that ACOG runs for your ACOG organization. For each exchange, ACOG signs a short-lived token for your organization and trades it at Anthropic for a short-lived access token that acts as a service account in your workspace. Read [Keyless connections](https://tessarac.com/docs/acog/providers/keyless-connections.md) for how this works.

You need the admin, owner or primary owner role in your Anthropic organization.

### 1. Get your organization's identity from ACOG

In ACOG, open **Admin → Providers → Connect provider**, choose **Direct** and **Anthropic**, and select **Keyless (workload identity)**. The console shows three values with copy buttons:

| Value | Example |
|---|---|
| Issuer URL | `https://api.acog.tessarac.com/v1/identity/q4ztn6xo2bk7wmy3hfr5lc2pda` |
| Subject | `acog:org:q4ztn6xo2bk7wmy3hfr5lc2pda` |
| Audience | `https://api.anthropic.com` |

Keep this page open; you will come back to it.

### 2. Set up federation in the Claude Console

Go to **Settings → Workload identity** in the [Claude Console](https://platform.claude.com/settings/workload-identity-federation) and choose **Connect workload**, then **Custom OIDC**. Create:

1. **An issuer.**
   - Issuer URL: your ACOG issuer URL, exactly as shown.
   - Key source: **discovery**. Anthropic fetches ACOG's public keys from the issuer URL.
   - The issuer's maximum token lifetime must be at least 30 minutes (the default, one hour, is fine). ACOG's tokens are valid for 30 minutes.
2. **A service account** in the workspace whose limits and billing ACOG's traffic should use.
3. **A federation rule** for that issuer:
   - Subject: your ACOG subject, exactly, with no trailing `*`. This is what makes the rule accept your organization and nothing else.
   - Audience (optional): `https://api.anthropic.com`.
   - Target: the service account, in that workspace.
   - Scope: `workspace:developer`.

Note the **rule ID** (`fdrl_…`) and the **service account ID** (`svac_…`). Your **organization ID** (a UUID) is under **Settings → Organization**. If the rule covers more than one workspace, note the **workspace ID** (`wrkspc_…`) too.

### 3. Finish the connection in ACOG

Back in the ACOG console, enter the organization ID, federation rule ID, service account ID and, if needed, the workspace ID. Save. ACOG performs a token exchange and lists your models to confirm the setup.

Anthropic's **Authentication history** tab on the Workload identity page shows each exchange ACOG makes, and the reason for any that fail.

### What ACOG sends

For each exchange ACOG calls `POST https://api.anthropic.com/v1/oauth/token` with a JWT-bearer grant naming your rule, service account, organization and workspace. It then calls the Messages API with `Authorization: Bearer <access token>` and the `oauth-2025-04-20` beta flag, and never sends an `x-api-key`. Each token ACOG signs carries a fresh `jti`, so Anthropic's single-use check stays on.

### Switching an existing connection to keyless

Edit the connection, select **Keyless (workload identity)** and fill in the identifiers. When you save, ACOG deletes the stored API key. Delete the key in the Claude Console afterwards. Switching back to an API key requires entering a key again.

### Removing access

To cut ACOG off immediately, delete or disable the federation rule (or the issuer) in the Claude Console. Access tokens ACOG already holds expire within the rule's token lifetime.

## Settings

| Setting | Notes |
|---|---|
| Base URL | Defaults to `https://api.anthropic.com`. Change it only for an Anthropic-compatible endpoint. On the hosted service it must be a public HTTPS address on port 443. |
| Models | The Claude models this connection serves. See [Connecting providers](https://tessarac.com/docs/acog/providers/overview.md#declared-models). |
| Default model | Used for `model: "auto"` when this is your default connection. |
| Cache lifetime | How long Anthropic keeps prompt-cache entries ACOG creates: 5 minutes or 1 hour. See [Caching](https://tessarac.com/docs/acog/optimize/caching.md#cache-lifetime). |

## Calling Anthropic through ACOG

Any of your models can be called through the [Messages API](https://tessarac.com/docs/acog/api/messages.md) or the [Chat Completions API](https://tessarac.com/docs/acog/api/chat-completions.md). To use the Anthropic API exactly as Anthropic defines it, including endpoints ACOG does not translate (token counting, Message Batches, Files), use the native route `https://gateway.acog.tessarac.com/anthropic`. See [Native provider routes](https://tessarac.com/docs/acog/api/native-routes.md).

## Troubleshooting

| What you see | Cause | Fix |
|---|---|---|
| `422 upstream_auth_failed` on an API-key connection | Anthropic rejected the stored key | Paste a valid key into the connection |
| `502 upstream_auth_error` on a keyless connection | Anthropic refused the token exchange | Open **Authentication history** in the Claude Console for the reason. Check the rule's issuer URL and subject match ACOG's values exactly, and the IDs entered in ACOG |
| `authentication_error` with reason `jti_reused` | The same token was presented twice | Only possible on a self-hosted install using its own identity for several connections; see [Install identity](https://tessarac.com/docs/acog/self-hosted/install-identity.md) |
| `422 model_access_required` | Your Anthropic workspace cannot use the model | Check the model is available to the workspace |

After a refused exchange ACOG waits 30 seconds before trying that connection again, so a misconfiguration does not flood your authentication history.