Proxy
The proxy is STACK's controlled path for outbound HTTP calls. It verifies the Passport, enforces scope and parameter constraints, injects the credential, and forwards the call upstream. An agent that uses this path does not receive the raw secret.
STACK cannot govern a call that bypasses the proxy. Passport checks, proxy detectors, and proxy audit records apply only to calls sent to /v1/proxy.
Request shape
One endpoint, one header, one body. The X-Passport-Tokenheader carries the signed passport; the body describes the upstream call exactly as you would send it directly. Non-GET calls also carry a stable X-STACK-Authority-Request-Id operation handle.
POST /v1/proxy
X-Passport-Token: eyJhbGciOi...
X-STACK-Authority-Request-Id: operation_job_4821_message_0001
Authorization: Bearer $STACK_TOKEN
{
"service": "slack",
"method": "POST",
"url": "https://slack.com/api/chat.postMessage",
"headers": { "Content-Type": "application/json" },
"body": { "channel": "C0123", "text": "hi" }
}Call pipeline
Steps 1-9 run before the upstream call. A failure in those steps prevents the call. After the provider responds, STACK screens and stores the permitted response before returning it.
- 1. Verify passport signature, expiry, revocation state
- 2. Tier + overage check (proxy call counts against the operator's monthly allowance)
- 3. Intent approval - enforced Passports must present the approved Intent for this call
- 4. Authority check - when the Passport carries authority_refs, resolve the exact active binding and enforce its agent key, receiver, action, resource, Mission, limits, validity, and approval state
- 5. Scope check - the service must be in the operator grant and any declared intent
- 6. Operation policy and parameter constraints - every applicable rule must pass
- 7. Operation admission for writes - bind the stable operation handle to the exact prepared request and acquire one dispatch owner
- 8. Credential injection - decrypt the credential server-side and build auth headers
- 9. URL resolution - substitute configured provider placeholders
- 10. Forward upstream; enforce response size (10 MB) and request timeout (30s)
- 11. Screen and redact the response before returning or storing it; record detector signals, the authority use when applicable, and the audit entry
Safe retries for writes
Persist the operation handle before a non-GET call leaves the process. An unchanged retry with the same handle joins the first operation and can return its stored permitted response. A changed request conflicts. Generic HTTP operations receive one STACK dispatch; when the provider may have acted but no response can be proved, STACK reports the outcome as unknown instead of automatically sending the write again. Stripe refunds can use Stripe's native idempotency and provider lookup to recover the original refund.
Stored response payloads are encrypted and readable for up to 24 hours. Status and response reads require current access to the original agent, connection and request scope. The operation handle never grants access by itself. See Proxy API recovery.
Proxy mediation proves that STACK enforced the binding. It does not prove that the receiver independently verified a native signed-and-encrypted presentation. Native receiver verification uses the separate authority protocol.
What the proxy enforces
- Service scope - only services in the passport can be reached. Anything else throws credential_outside_scope and a 403 FORBIDDEN.
- Parameter constraints - see /docs/concepts/constraints. Can tighten to a specific channel, repo, customer ID, or regex-matched URL path.
- Response size - capped at 10 MB. Larger upstream responses are rejected.
- Request timeout - 30 seconds. An upstream timeout returns 504 for GET. For a write that may have reached the provider, STACK returns 202 with outcome_unknown and does not resend it automatically.
- Revocation - a revoked passport fails verification before the upstream call is made.
Credential injection
Credentials live encrypted in the vault with KMS envelope encryption. At step 8, the proxy decrypts in-memory, builds the upstream auth header per the provider's convention (OAuth Bearer, basic, custom HMAC, etc.), and attaches it to the forwarded request. The agent does not receive the plaintext credential. The proxy call writes an audit entry.
Agent credential access modes
Agents declare credential_access to scope how they can reach services. The proxy honours the mode at verify time.
- proxy_only (default) - STACK rejects raw credential retrieval for the agent; connected credentials can be used through the proxy
- proxy_preferred - the same raw-retrieval restriction, labelled for runtimes that normally use the proxy without treating it as a deployment boundary
- direct - agent can both retrieve credentials (/v1/credentials/:provider) and use the proxy. What it does with a retrieved credential is outside STACK.
These modes govern credentials held by STACK. They do not sandbox the runtime or block direct network calls made with credentials obtained elsewhere.
Related
- /docs/concepts/passports - what verify checks
- /docs/concepts/authority - externally proved authority and receiver verification
- /docs/concepts/constraints - parameter-level rules enforced at step 5
- /docs/concepts/intents - named shortcut constraints
- /docs/concepts/detectors - runtime signals recorded during the proxy flow
- /docs/api/proxy - complete endpoint reference