Custom backends

Codex works by default. Customize Paper backends — recreate them on a custom gateway, or set up a team-managed OpenAI key.

Codex works by default

When you select an org, Paper provisions a default gateway with two transparent Codex backends attached:

  • chatgpt-codex (schema ChatGPTCodex → chatgpt.com) for ChatGPT-plan auth.
  • openai-transparent (schema OpenAI → api.openai.com) for per-user OpenAI keys.

Neither stores a key, so paper start codex works with no setup — Codex’s own ChatGPT OAuth or the caller’s OPENAI_API_KEY reaches OpenAI directly.

You only need the rest of this page to set up a shared team key, or to recreate these backends on a custom gateway. A backend is one route from your gateway to a single upstream provider, and Codex runs through Paper in three shapes:

  • ChatGPT passthrough auth, where Codex sends its own ChatGPT-plan OAuth token. (auto-created)
  • Per-user OpenAI API-key passthrough, where Codex reads OPENAI_API_KEY from the user’s environment and Paper forwards that credential through to OpenAI. (auto-created)
  • Team-managed OpenAI API-key auth, where Paper stores one OpenAI API key on the backend and injects it for users routed through that gateway. (manual — see Option B)

The paper tapes backend create calls below are idempotent, so re-running them against default is safe.

Before you start

You need:

  • paper login completed for the target organization.
  • A gateway name. Use paper status or paper tapes gateway list to find it.
  • An OpenAI API key if you want OpenAI API-key auth.

The examples below use default as the gateway name.

Create the ChatGPT passthrough backend

Use this backend for Codex ChatGPT-plan auth. Do not pass --auth-type or --api-key; the upstream only honors the OAuth token supplied by Codex itself.

paper tapes backend create \
  --gateway default \
  --name chatgpt-codex \
  --schema ChatGPTCodex \
  --upstream chatgpt.com \
  --model '.*'

paper start codex routes ChatGPT-plan traffic through /v1/openai-chatgpt/chatgpt-codex, so keep the backend name chatgpt-codex.

Option A: Per-user OpenAI API-key passthrough

This is the openai-transparent backend Paper already created on the default gateway. Recreate it only on a custom gateway. Use this shape when each user should authenticate with their own OpenAI API key from their environment. Do not pass --auth-type or --api-key; Paper leaves the Authorization header supplied by Codex intact.

paper tapes backend create \
  --gateway default \
  --name openai-transparent \
  --schema OpenAI \
  --upstream api.openai.com \
  --model '.*'

The backend name is free-form. paperd attributes direct OpenAI Responses traffic to Codex by route schema (OpenAI / openai-responses), not by a name prefix, so the route works whatever you call the backend.

Users launch Codex with their own key:

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

Option B: Team-managed OpenAI API key

Use this backend when the team should share one OpenAI API key managed by Paper. Paper stores the key on the backend and injects it on requests routed through this gateway.

A gateway routes direct Codex API-key traffic through exactly one OpenAI backend, and default already has the transparent openai-transparent. So a team-managed key is not additive: either delete openai-transparent from default first and recreate it as managed, or attach the managed backend to a separate gateway (see Routing constraints).

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

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

After the backend is created, users do not need a real OpenAI API key locally for this gateway. Today paper start codex uses the presence of OPENAI_API_KEY to choose the OpenAI Responses route, so set a placeholder value when launching through a team-managed backend:

export OPENAI_API_KEY="paper-managed"
paper start codex

The placeholder only selects Codex’s API-key provider path. The gateway injects the team key stored on the backend before the request reaches OpenAI.

Routing constraints

The direct Codex routes are intentionally unambiguous:

  • A gateway should have exactly one ChatGPTCodex backend for ChatGPT passthrough auth.
  • A gateway should have exactly one OpenAI backend if you want API-key Codex traffic to use the direct Responses route. Pick either per-user key passthrough or team-managed key injection on that gateway, not both.

If you need both OpenAI key strategies, or multiple OpenAI backends for other traffic, create separate gateways.

Verify the backends

List the gateway backends:

paper tapes backend list --gateway default

Check that the backend rows show:

  • chatgpt-codex with schema ChatGPTCodex and transparent auth.
  • An OpenAI-schema backend — the auto-created openai-transparent (transparent, per-user keys) or your openai-managed (managed auth, team key).

Then restart or reconfigure paperd so it picks up the route:

paper init
paper status

Try both Codex modes

For ChatGPT passthrough auth, make sure OPENAI_API_KEY is unset or blank, then launch Codex:

unset OPENAI_API_KEY
paper start codex

For per-user OpenAI API-key auth, set the key before launching:

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

For team-managed OpenAI API-key auth, set a placeholder so Codex uses the OpenAI Responses route:

export OPENAI_API_KEY="paper-managed"
paper start codex

All modes should show Codex sessions in paper console. If sessions appear without turns, confirm the backend name and schema match the examples above and check paper logs for routing or attribution warnings.

Copied to clipboard