> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencomputer.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Credentials

> Run models Managed (billed to your credits) or on your own provider keys

A session runs a model one of two ways:

* **Managed** — run it **through OpenComputer**, billed to your **credits**, with **no key to manage**. The default for new orgs, and selectable per agent. Nothing to store, rotate, or protect.
* **Bring your own key (BYO)** — your own provider key (Anthropic for the `claude` [runtime](/agent-sessions/runtimes), OpenAI for `codex`), stored once as a **credential** and reused across [agents](/agent-sessions/agents). It's treated as a hard secret end to end: **encrypted at rest, never returned by the API, and never present inside a sandbox.**

You don't strictly need a credential: an agent set to Managed needs no key. A session only fails to start (`422 no_credential`) when it resolves to **neither** Managed **nor** a usable key. The rest of this page is about BYO credentials; for Managed, just select it per agent (below).

## Managed vs BYO

|         | **Managed**                                                        | **BYO credential**          |
| ------- | ------------------------------------------------------------------ | --------------------------- |
| Key     | none — run via OpenComputer                                        | your Anthropic / OpenAI key |
| Billing | your OpenComputer **credits**                                      | your provider invoice       |
| Setup   | select it per agent (`credential: "managed"`)                      | add a credential (below)    |
| Models  | same `provider/model` ids, per [runtime](/agent-sessions/runtimes) | same                        |

Pick per agent: `credential: "managed"` runs Managed; a `cred_…` id (or an inline `key`) runs BYO; omit it to inherit the org default. New orgs default to Managed, so you can start with **no key at all** and switch to BYO whenever you want. The rest of this page covers BYO.

## How your keys are protected

Two independent layers — at rest and in use:

* **At rest: a dedicated secrets vault.** Your key is stored in [Infisical](https://infisical.com), a battle-tested, purpose-built secrets platform — encrypted at rest and isolated from OpenComputer's own database. It's **write-only**: once submitted it's never returned by the API (reads expose only a `last4` display hint).
* **In use: never handed to the agent.** The real key never enters the sandbox. The runtime runs with an opaque placeholder, and OpenComputer's [secret-store egress proxy](/sandboxes/secrets) swaps in the real value **in flight** — only on the outbound HTTPS call to the model provider (`api.anthropic.com` / `api.openai.com`), enforced by an egress allowlist, and nowhere else.

Rotating a key's value reaches **running** sessions too, so a compromised key retires without restarting work ([rotation](#rotation)).

<Warning>Keep your **org API key** (which manages credentials) on your backend, and hand browsers only session-scoped [client tokens](/agent-sessions/authentication#client-tokens) — never a model key or the org key.</Warning>

## Add a credential

<Tip>Skip this entirely with **Managed** — set an agent's `credential` to `"managed"` (or rely on the org default) to run via OpenComputer billed to your credits, no key required. See [Managed vs BYO](#managed-vs-byo) below.</Tip>

Set `provider` to `anthropic` or `openai`. `name` is an optional label; `is_default` makes it your org default for that provider (see [resolution](#resolution)). The response is the credential's **metadata only** — the key is never echoed back.

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  const cred = await oc.credentials.create({
    provider: "anthropic",
    key: "sk-ant-...",
    name: "prod",
    isDefault: true,
  });
  // → { id: "cred_…", provider: "anthropic", name: "prod", last4: "AB12", isDefault: true, createdAt: "…" }
  ```

  ```http REST API theme={null}
  POST https://api.opencomputer.dev/v3/credentials
  Authorization: Bearer $OPENCOMPUTER_API_KEY
  Content-Type: application/json

  { "provider": "anthropic", "key": "sk-ant-...", "name": "prod", "is_default": true }
  ```
</CodeGroup>

Attach it to an agent by id, so the agent runs on it:

```ts TypeScript SDK theme={null}
await oc.agents.create({ name: "reviewer", runtime: "claude", model: "anthropic/claude-opus-4-8", prompt: "…", credential: cred.id });
// …or run Managed (billed to credits, no key):
await oc.agents.create({ name: "reviewer", runtime: "claude", model: "anthropic/claude-opus-4-8", prompt: "…", credential: "managed" });
```

<Tip>Prefer not to touch the API? Add and manage credentials from the [dashboard](https://app.opencomputer.dev) under **Agents → Credentials** — and pick one (or add a new one inline) right in the create-agent dialog.</Tip>

## List, default, and remove

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  const creds = await oc.credentials.list();           // metadata only (last4, never the key)
  await oc.credentials.setDefault({ credential: "cred_..." });
  await oc.credentials.delete("cred_...");
  ```

  ```http REST API theme={null}
  GET    https://api.opencomputer.dev/v3/credentials
  PUT    https://api.opencomputer.dev/v3/credentials/default      { "credential": "cred_..." }
  DELETE https://api.opencomputer.dev/v3/credentials/:id
  ```
</CodeGroup>

The credential object: `{ id, provider, name?, last4, is_default, created_at }`. `last4` is the last four characters, for display — the key itself is never returned.

<Warning>Deleting a credential breaks agents pinned to it and sessions that fall back to it, until you point them at another credential, at **Managed** (`credential: "managed"`), or set a new default. If your org has no other default, they fall back to Managed automatically.</Warning>

## Resolution

When a session is created, its model source is resolved (and **pinned** for the session's life) in this order:

1. The agent's **`credential: "managed"`** → run Managed, billed to your credits.
2. The **agent's** BYO credential, if it has one and it matches the runtime's provider.
3. Your **org default** BYO credential for that provider.
4. **Managed**, if your org has no BYO default — so a new org runs Managed out of the box.

Only if **none** resolves does the session fail to start: `422 no_credential` (no Managed and no usable key), or `422 managed_unavailable` (Managed selected/defaulted but not yet active for your org).

## Rotation

Rotating the **key value** behind a credential flows to **running** sessions too — the one exception to a session's otherwise [pinned config](/agent-sessions/agents#session-pinned-config), so a compromised key can be swapped without restarting work. Rotate the credential:

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  await oc.credentials.rotate("cred_...", "sk-ant-NEW...");
  ```

  ```http REST API theme={null}
  PATCH https://api.opencomputer.dev/v3/credentials/cred_...
  Authorization: Bearer $OPENCOMPUTER_API_KEY
  Content-Type: application/json

  { "key": "sk-ant-NEW..." }
  ```
</CodeGroup>

Passing a new `key` to [`oc.agents.update`](/agent-sessions/agents) still works as a shortcut — it rotates the agent's attached credential.

Changing **which** credential an agent uses (a different `credential` id) affects only **future** sessions — existing sessions keep the one they pinned.

## Shortcut: add a key inline

For the true **no-key** path, use [Managed](#managed-vs-byo) (`credential: "managed"`) — nothing to store. If you're going BYO, you rarely call the credentials API directly: the common path is to pass the key **inline** when you [create an agent](/agent-sessions/agents) — it's stored as a credential (with all of the protections above) and attached to the agent in one call. The provider is inferred from the agent's `model` (`anthropic/…` → Anthropic, `openai/…` → OpenAI).

<CodeGroup>
  ```ts TypeScript SDK theme={null}
  await oc.agents.create({
    name: "reviewer",
    runtime: "claude",
    model: "anthropic/claude-opus-4-8",
    prompt: "Review the repo. Run tests. Summarize risks.",
    key: "sk-ant-...",
  });
  ```

  ```http REST API theme={null}
  POST https://api.opencomputer.dev/v3/agents
  Authorization: Bearer $OPENCOMPUTER_API_KEY
  Content-Type: application/json

  { "name": "reviewer", "runtime": "claude", "model": "anthropic/claude-opus-4-8", "prompt": "…", "key": "sk-ant-..." }
  ```
</CodeGroup>

Reach for the standalone resource above when you want to reuse one key across agents, set an org default, or rotate / remove keys.