Skip to main content
The HTTP secret proxy lets a user or service account use a credential without exposing the secret value to the caller.
Add user={email} when the request should use a user-owned secret for a specific user.

Authorization

OAuth callers must own the user secret. If user is supplied, it must match the OAuth subject. API-key callers run as the API key’s service account. The service account must have use_proxy_secrets, and the target secret must grant that service account per-secret use_proxy.

Delegating a connector to an agent

Studio and Powerboards request a short-lived proxy capability immediately before sending an MCP turn. The signed-in account token stays in the application; agents receive only a credential for the selected secret and exact connector URL. An account OAuth caller with secrets:proxy can mint one through POST /accounts/users/me/secrets:proxy-capability with this JSON body:
The response contains token and expires_at. Send Authorization: Bearer <token> to /proxy-request with the same secret-id and url. A capability lasts at most ten minutes. It cannot read or manage secrets, mint more credentials, select another user, inject additional headers, or change the target path or query. Every request rechecks the parent account session, ownership, and resource-origin policy; revoking the session or deleting the secret disables outstanding capabilities. A live stream is not interrupted solely because the credential expires, but reconnecting requires a fresh capability. Deploy the supporting router before the updated applications. Older routers cannot mint capabilities; applications fail the send instead of falling back to an account bearer. Configure the resource-origin policy below before use. Existing trusted server-side API-key proxy callers retain their normal authorization flow.

Approved resource origins

Before using a secret through the proxy, its owner or service-account secret manager must set an exact resource-origin policy in the secret’s metadata:
Set this metadata when creating or updating the secret through the SDK, CLI, or Studio metadata editor. Preserve any other metadata when updating it. Proxy-only delegates cannot change this policy. Origins contain a scheme, host and optional port; paths, credentials, queries, fragments and wildcards are rejected. Subdomains and non-default ports require their own entries. wss uses the corresponding https origin and ws uses http. Existing secrets without this policy cannot be proxied until an owner configures it. Discovery annotations such as meshagent.io/secret.url are not an authorization policy. Every secret in a multi-header request must approve the destination before any secret is decrypted or refreshed. WebSocket redirects must remain within the origins approved by every injected secret; HTTP redirects are returned without following them. For OAuth secrets, allowed_origins describes the resource server, which can differ from the saved token endpoint. Refresh requests may follow redirects only within the token endpoint’s own origin. All destinations must also pass the public network policy. Configure only resource origins you trust with the credential; this policy does not restrict paths within an approved origin.

Behavior

For an opaque secret, the proxy sends Authorization: Bearer <secret value>. Store only the token, without the Bearer prefix. OAuth credential secrets use their saved token type and access token and are refreshed when needed. Managed-agent HTTP connections can also map several secrets to named headers; see Managed Python Tools. The proxy supports normal HTTP requests, WebSocket upgrades, and streaming SSE responses.