# Giving an agent credentials

> How an agent's credentials are described (AgentIdentity), what types exist, and the guided flows that set them up.

Source: https://openap.org/docs/giving-credentials

An `agent`-identity agent needs its own credentials, and a `userPassthrough` agent needs
yours. Either way, OAP describes credentials as named, typed *references* — never a pile of secret
bytes the process inherits.

## AgentIdentity — a named credential set

An **`AgentIdentity`** is the set of credentials an agent acts as: reusable, typed descriptors that toolkits and
MCP servers request *by name*. It carries references to Secrets, never the token bytes themselves — the actual
values are resolved at runtime, just-in-time, by the token broker.

## Credential types

Each credential declares a type, and the type decides how it's stored and refreshed:

- **`static`** — a fixed secret value (a key in a Secret): a PAT, an API key, a kubeconfig.
- **`oauth`** — an OAuth credential (access + refresh token, expiry, endpoints), proactively refreshed before it
  expires.
- **`federated`** — *no stored token at all*; minted on demand from the user's enterprise identity. Passthrough
  only. (See **Enterprise managed auth**.)
- **`githubApp`** — a short-lived installation token minted from a stored GitHub App private key. The
  agent-identity mirror of `federated`.

## Guided setup flows

Getting a credential in place is a guided flow, not a raw secret paste. OAP ships curated flows for the common
cases — creating a GitHub fine-grained PAT, capturing Claude Code's setup token, importing a kubeconfig, an
OAuth + PKCE dance against an MCP server, minting a Tailscale auth key — each of which walks you through the
provider's own UI and then **verifies the credential is live before storing it**. A credential that doesn't
verify is shown back to you, not silently saved. For providers without a curated flow, an LLM-driven flow reads
the provider's docs and guides you through.

> **Security: A valet key, not the keyring**
>
> The model never sees a credential's bytes: the broker resolves a descriptor into an injectable env var or
> header for the one tool that needs it (per call for sandbox tools, at session start for MCP servers and
> sidecars). An agent holds references to what it
> may use — not the workspace's whole set of secrets. See [ASI03](https://openap.org/docs/owasp-top10#asi03).
