---
name: "agent_auth_patterns"
description: "Designs credential architecture for AI agents: scoped short-lived tokens, delegated OAuth on behalf of users, token-broker patterns, and rotation policy. Triggers when an agent needs to authenticate to APIs or tools, choose an OAuth flow for an agent, scope tokens, or design a token lifecycle and audit plan."
---

# Agent Auth Patterns

Design how an agent holds credentials so a compromised, confused, or prompt-injected agent still cannot do damage beyond what it was explicitly granted.

## Purpose

Turn "the agent needs access to X" into a concrete, reviewable auth plan: which identity acts, which flow mints the credential, how tight the scope is, how short the lifetime is, and who can audit and revoke it.

## Workflow

1. **Map the identities.** Every agent call answers three questions: who authorized it (user, tenant, system), which agent acts, and whose data it touches. If no person is acting, that is a machine identity case, not a delegated OAuth case. Write this down first; everything else hangs off it.

2. **Pick one flow per relationship.**
   - A person acts through the agent: delegated OAuth, Authorization Code + PKCE, scopes equal to what the user consented to. The token carries the user identity, and revoking consent kills the token immediately. A shared service account for user actions is the fallback, never the default.
   - The agent acts as itself (cron, pipeline, deployment): workload identity federation. The runtime proves who it is with an OIDC token to an exchange service, which mints a short-lived credential scoped to exactly one resource. No long-lived static key anywhere the agent can keep.
   - The agent calls a third-party tool server: a credential broker injects the credential at call time. The agent names the connection; the broker attaches the token. The model never sees the raw credential.

3. **Scope tokens with the two-level hierarchy.** Resource plus action qualifier: `database:read`, `files:write`, `github:read`. Granular enough to enforce least privilege, coarse enough to stay manageable. Separate read-only tools from write tools; anything irreversible (publish, delete, payout) gets its own scope and an approval gate. Write-only-on-scope is defense in depth at the identity layer: even if the agent goes sideways, the token cannot take actions it was never authorized for.

4. **Make tokens short-lived and rotation automatic.** Target 5-15 minute access token lifetimes. Refresh tokens are high-risk secrets: encrypt them at rest, treat them like production secrets, rotate them on a schedule. Agent-local static keys with no expiry are a defect, not a design; dynamic credentials on demand with a lease the broker auto-revokes is the goal.

5. **Bind tokens to their audience.** When the platform supports it (MCP servers with RFC 8707 resource indicators), the token is minted for one server and the server validates the audience on every call. Never accept a token issued for another service, and never forward a received token upstream. Each hop gets its own token.

6. **Keep credentials out of the model's world.** No credential material in prompts, traces, logs, or tool results the model reads. Storage, scoping, refresh, and audit live in the dedicated broker layer, not in the agent's code. If the agent can keep a long-lived admin credential in memory, the model is too broad. Fix the architecture, not the prompt.

7. **Audit every issuance and every call.** Log who authorized, which agent acted, which credential was issued, what it was scoped to, and what it did. Redact the token material itself. Audit is the half of security you cannot bolt on later.

## Output Contract

Produce an **auth plan** covering: the identity map (who authorizes, which agent, which tenant), one flow per relationship, the scope set with action qualifiers, token lifetimes and rotation policy, the broker or store that holds each credential, the approval gates for irreversible scopes, and how issuance and calls get audited. Validate it with `bin/scope_check.py plan.yaml` before shipping it.

## Operating Rules

1. Every factual claim about a protocol or limit must be verified against a primary source or cut. The sources behind this skill are in `references/`.
2. Prefer delegated user OAuth over service accounts, workload identity over static keys, brokers over hand-rolled token management.
3. Never invent flow details a platform does not document; check the platform's auth docs for the exact grant, scope names, and lifetimes.
4. Prefer minimal scopes: default read-only, add write scopes only where the workflow provably needs them.
5. Credentials never appear in prompts, logs, traces, or SKILL.md examples; use placeholders like `<token>`.
6. Run `bin/scope_check.py` on every plan; a plan that fails validation does not ship.