Runtime auth

By default a capability uses one key, stored as a secret on the capability Worker. That fits one app and one provider account.

cf

cf workers secrets update STRIPE_API_KEY --worker capa-stripe --type secret_text

Wrangler

wrangler secret put STRIPE_API_KEY

Runtime auth lets one deployed capability serve many accounts. Pass the key for this call in options.auth.

await env.STRIPE.paymentIntents.create(
  { amount: 2500, currency: "usd" },
  { auth: { apiKey: tenant.stripeKey } },
);

The per-call key wins. If you pass none, the capability uses its secret. If it has no secret either, the call throws: set the capability API key secret or pass options.auth.apiKey.

Mode	Where the key comes from	Use it for
Worker secret	STRIPE_API_KEY on capa-stripe	One app, one provider account
Runtime auth	options.auth on each call	One capability, many accounts
Gateway vault	Each user’s vault in capa-gateway	Agents acting for many users

The options

options is always the last argument.

interface CallAuth {
  apiKey?: string;
  username?: string;
  password?: string;
  headers?: Record<string, string>;
}

Field	Use it for
apiKey	Bearer and Private-Token APIs, such as Stripe, GitHub, and GitLab.
username and password	Basic auth APIs, such as HTML/CSS to Image.
headers	Extra headers a provider requires, such as Twitch Client-Id.

Providers that need extra headers

Twitch needs a token and a client ID on every request:

await env.TWITCH.channels.list({
  query: { broadcaster_id: "141981764" },
  auth: {
    apiKey: tenant.twitchToken,
    headers: { "Client-Id": tenant.twitchClientId },
  },
});

How capa-gateway uses it

The gateway keeps each user’s keys in a vault. When an agent’s code calls a capability, the gateway reads that user’s key and adds it as options.auth. The agent’s code never sees the key, and the capability needs no secret of its own.

Boundaries

Runtime auth does	Runtime auth does not
Set the key or credentials for one call	Change the upstream base URL per call
Add provider auth headers	Store tenants or keys
Fall back to the Worker secret	Refresh OAuth tokens

Security

• Evidence records hold the method, the URL, and the status. They never hold auth values or request headers.
• Errors do not echo key values.
• Use the narrowest key the provider offers, such as a restricted Stripe key or a fine-grained GitHub token.