APIZ guide

Understand APIZ Credential Boundaries

An agent needs permission to use a service, but it usually does not need the service's original credential. APIZ separates those two concerns.

agent or sandbox              APIZ                         upstream service
----------------              ----                         ----------------
Temporary Credential  --->    validate request
                              apply Policy
                              resolve protected secret
                              replace APIZ credential ---> upstream credential
                       <---   redacted result/evidence <--- response

The Three Credentials You May Encounter

Credential	What it authenticates	Where it belongs	Typical lifetime
Upstream credential	APIZ to GitHub, Notion, Cloudflare, or another service	Encrypted API Instance secret; resolved only inside APIZ	Until rotated or revoked at the provider
Temporary Credential	An agent or tool to an APIZ Client Binding	The agent runtime that needs the bounded access	Short-lived and revocable
APIZ login session	A person or administrator to the Control Plane	The user's CLI or browser session	Interactive session lifetime

The CLI contract calls a Temporary Credential a Client Access Credential. The Web Console uses the friendlier Temporary Credential name. They are the same APIZ-scoped credential, not a copy of the upstream secret.

What Happens On Every Request

APIZ validates the Temporary Credential and resolves exactly one Client Binding.
The adapter recognizes and validates the intended upstream operation.
APIZ evaluates attached Client Binding Policies, then attached API Instance Policies. An evaluation error denies the request.
The Secret Broker releases the active upstream credential only for the current allowed decision.
APIZ removes APIZ-only authentication and applies the upstream credential inside the protected Data Plane path.
APIZ records required authorization evidence with credential values and other sensitive fields redacted.

No optional Policy is required for credential separation. Without a Policy, APIZ still requires a valid binding, validates the request through the adapter, overwrites credentials, protects secret resolution, and records redacted evidence.

The Objects Behind The Boundary

API Instance ── stores one configured upstream connection and its secret
      ▲
      │ selected by
Client Binding ── gives one Client a named route to that API Instance
      ▲
      │ belongs to
Client ── represents the agent, sandbox, application, or developer tool
      │
      └── issues one or more Temporary Credentials in a Credential Group

Policy (optional) ── attaches to a Client Binding or API Instance

A Credential Group is the lifecycle record for one issuance operation. Revoking the group revokes every still-active credential issued together.

Safe Handling Rules

Enter an upstream credential only while creating or rotating an API Instance.
Never paste an upstream credential into Policy source, fixtures, agent prompts, logs, or Setup Manifest files.
Treat a Setup Manifest as sensitive: it contains APIZ-issued plaintext credentials and is shown intentionally at issuance time.
Give each agent the shortest practical credential lifetime and only the bindings it needs.
Revoke a Credential Group when a task ends early or its runtime may be compromised.
Use Access Logs and Audit Events for investigation; do not add secret values to labels or metadata to make requests easier to find.

Next: connect an API or give an agent access.