Gateway API keys and direct access

Some model traffic can’t go through paperd: a CI job, a deployed service, a script on a machine where nobody ran paperctl login. Gateway API keys are how that traffic still goes through your gateway — so it’s still captured, still governed by your backends, and still attributed to you.

A gateway API key is a per-user credential that stands in for the identity paperd normally attaches. It answers “who is making this request” — it does not pay for model calls.

Before you start:

• A managed backend on the gateway you’ll call. A direct caller brings no provider credential, so the gateway must inject one; on a transparent-only gateway, direct requests have nothing to authenticate to the provider with.
• Access to paper console.

Create a key

1. In the console, open the API keys page.
2. Create a key and give it a name that says where it will live — ci-deploys, eval-runner.
3. Copy the key when it’s shown. The full value (it starts with paper_) is displayed once, at creation; afterwards the list shows an obfuscated version.

Keys are per user, not per gateway: the list shows only your own keys, a key works on any of your organization’s gateways, and sessions produced with it are attributed to you.

Call the gateway

Get the gateway’s endpoint from the console’s Gateways page or the CLI (paperctl tapes gateway get <name>). Point an OpenAI-compatible SDK at it with your key as the API key — the console shows this exact pattern:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PAPER_API_KEY"],
    base_url="<your gateway endpoint>/v1",
)
response = client.chat.completions.create(
    model="<a model your backends allow>",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

The key travels in the standard Authorization: Bearer header, which is what SDK api_key parameters set. Chat Completions and Anthropic Messages requests are supported on the direct path; the Codex/Responses API and provider administrative APIs are not.

Use a model name a backend on this gateway allows — the model allowlists apply to direct traffic exactly as they do to paperd traffic.

Verify it worked

Send one request, then check your session history:

paperctl sessions list

The request shows up as a captured session in your organization — that’s the point of routing direct traffic through the gateway instead of straight to the provider.

Revoke a key

Revoke from the same API keys page. Every request is checked online, so a revoked key stops working immediately. Revoke keys you can’t account for and rotate keys that lived anywhere shared.

When to use keys vs paperd

• paperd for people: interactive agent sessions on machines where paperctl login runs. Identity refreshes itself; nothing to store.
• API keys for machines: CI, deployed services, notebooks, SDK code. The key is a stored secret — scope one key per place it lives, so revoking one doesn’t break the others.

Where to go next

• Backends and providers — set up the managed backend direct access requires.
• Export session data — pull the sessions your automation produces.