Do I need to configure backends for Claude Code or Codex to work?

No. The default gateway ships with working transparent backends for Anthropic, OpenAI, and ChatGPT Codex traffic. You configure backends to set a shared team key, restrict models, or build out a custom gateway.

Which schema do I pick for a provider that isn't Anthropic or OpenAI?

Usually OpenAI. Most model providers and neoclouds — Fireworks, for example — serve an OpenAI-compatible API, so a backend with the OpenAI schema and the provider's host as the upstream is the shape they expect. Reach for a provider-specific schema only when the provider speaks its own dialect.

How do I rotate a managed key?

Recreate the backend with the new key — delete it and create it again with the same name, passing the new --api-key. Deleting a managed backend removes its stored key.

Backends and providers - Paper Compute Docs

A backend is one route from a gateway to a single provider. This page shows how to create and configure backends: which provider they point at, which models they allow, and whose credentials they use. You need it when you’re setting a shared team key, restricting model access, or building out a gateway beyond the provisioned defaults.

Before you start:

paperctl authenticated against the target organization.
A gateway name — paperctl status or paperctl tapes gateway list shows yours. The examples below use default.
A provider API key, if you’re setting up managed auth.

Backend anatomy

Every backend is defined by four things:

Field	Meaning
Schema	The request dialect the provider speaks: `Anthropic`, `OpenAI`, `AzureOpenAI`, or `ChatGPTCodex`. For most other providers and neoclouds (Fireworks, …), `OpenAI` is the one you want — OpenAI’s API shape is the industry’s common dialect.
Upstream	The provider host the gateway forwards to, e.g. `api.anthropic.com` (port defaults to 443).
Models	An allowlist of model-name patterns. `'.*'` allows every model; explicit names restrict the backend to them.
Auth type	Transparent (no auth type set): the caller’s own credential passes through. Managed (e.g. `--auth-type APIKey`): the gateway injects a key stored on the backend.

The default gateway’s three backends (ant-default, chatgpt-codex, openai-transparent) are all transparent with '.*' model allowlists — see the gateway overview.

Create a backend

From the console: open Gateways, select a gateway, and add a backend from its detail view — the form covers the same fields as the CLI.

From the CLI:

paperctl tapes backend create \
  --gateway default \
  --name <backend-name> \
  --schema Anthropic \
  --upstream api.anthropic.com \
  --model '.*'

--name is lowercase letters, digits, and hyphens.
--model repeats: --model claude-opus-4-8 --model claude-haiku-4-5-20251001, or a comma-separated list. Pass --model '.*' to allow everything.
Add --auth-type and --api-key for managed auth (below).
Creation is idempotent — re-running against an existing backend of the same name is safe.

Inspect, list, and delete with the matching verbs:

paperctl tapes backend list --gateway default
paperctl tapes backend get <name> --gateway default
paperctl tapes backend delete <name> --gateway default    # --yes skips confirmation

A new backend shows Pending in the console until it’s ready; traffic flows once it is.

Restrict which models the team can use

The model allowlist is the control for this. A backend created with explicit --model names rejects requests for anything else, so a gateway whose backends list only approved models is a gateway that only serves approved models. Requests for a model no backend allows fail — the error names the model, which makes the fix visible in paperctl logs.

Managed auth: a shared team key

A managed backend stores one provider key and injects it into every request routed through the backend. Use it when the team should share one key and one bill, instead of every laptop holding provider credentials.

paperctl tapes backend create \
  --gateway default \
  --name anthropic-managed \
  --schema Anthropic \
  --upstream api.anthropic.com \
  --auth-type AnthropicAPIKey \
  --api-key "$ANTHROPIC_API_KEY" \
  --model '.*'

The key lives on the backend in your organization’s gateway — it never lands in teammates’ shell profiles or paperd config. To rotate it, recreate the backend with the new key; deleting the backend removes the stored key.

Managed backends are also the prerequisite for gateway API keys: a caller presenting a paper API key brings no provider credential, so the backend has to supply one.

Codex: the three key options

Codex traffic runs through paper in three shapes. The first two work with zero configuration on the default gateway.

Codex’s own ChatGPT OAuth passes through the transparent chatgpt-codex backend. Make sure OPENAI_API_KEY is unset, then:

unset OPENAI_API_KEY
paperctl start codex

Keep this backend named chatgpt-codex if you recreate it on a custom gateway — ChatGPT-plan traffic routes by that name. Don’t set --auth-type on it; the upstream only honors Codex’s own OAuth token.

Per-user OpenAI API key (default)

With OPENAI_API_KEY set in your environment, Codex uses OpenAI’s API and paper passes your key through the transparent openai-transparent backend:

export OPENAI_API_KEY="sk-..."
paperctl start codex

Team-managed OpenAI API key

One OpenAI key stored on a managed backend, injected for everyone routed through it:

: "${OPENAI_API_KEY:?Set OPENAI_API_KEY before creating the backend}"

paperctl tapes backend create \
  --gateway default \
  --name openai-managed \
  --schema OpenAI \
  --upstream api.openai.com \
  --auth-type APIKey \
  --api-key "$OPENAI_API_KEY" \
  --model '.*'

Two more steps make launches use it:

Route Codex to the managed backend, per launch. The Codex API-key route names a specific backend, and it defaults to openai-transparent — so select the managed backend explicitly on each launch with paperctl start --gateway default --backend openai-managed codex. (Avoid paperctl tapes backend use for this: it changes your machine’s primary backend, which affects other traffic that follows the primary route, without being the mechanism Codex’s named route selection relies on.)
Set a placeholder key when launching. paperctl start codex chooses Codex’s API-key path based on whether OPENAI_API_KEY is set, so give it a placeholder — the gateway replaces it with the stored team key before the request reaches OpenAI:

export OPENAI_API_KEY="paper-managed"
paperctl start --gateway default --backend openai-managed codex

Verify a backend works

paperctl tapes backend list --gateway default

Confirm the backend row shows the schema and auth you expect, then run a short session through it and check paperctl sessions list. Sessions that appear with zero turns usually mean the route reached the wrong backend — check paperctl logs for routing or authentication warnings, and see CLI troubleshooting.

Where to go next

API keys and direct access — call the gateway from CI and SDKs.
Manage gateways — create a separate gateway for a different backend mix.
Capture with Codex — the day-to-day Codex workflow.

Backends and providers