Agents SDK

Security & limits

Credentials never live in the sandbox. The sandbox receives a short-lived JWT that identifies { user, team, vault_ids }. The vault proxy catches every outbound HTTPS request, looks up a credential whose host pattern matches the request's target host, walks the vault_ids in JWT order until it finds a match — then MITMs the TLS, injects the real token, and forwards upstream. No match → passthrough unchanged.

For the concept of a vault and how credentials are consumed, see Credential vaults.

The JWT

Signed with an RS256 key that lives only on the relay. Claims include the team ID, sandbox ID, user ID, and the ordered list of vault IDs for this run. The JWT expires before the sandbox can; if it's stolen from the sandbox, it can only be used to reach the proxy, and only to resolve the vaults it was scoped to.

Host matching

Each credential carries a host_pattern derived from its serverUrl. Matches are exact (api.github.com) or one-level wildcard (*.notion.com). Match is case-insensitive; trailing slashes and query strings are ignored.

TLS interception

Sandboxes trust a 21st-managed root certificate, installed into the OS trust store at template build time. The proxy terminates TLS using a leaf certificate signed by that root, reads the decrypted request, performs the credential injection, then opens a fresh outbound TLS connection to the real upstream and forwards the rewritten request. The sandbox never handles the real server certificate; the real server never sees the sandbox's placeholder value.

Fail-closed semantics

If the outbound request still contains any recognizable placeholder after the proxy has finished rewriting it, the proxy drops the request before it leaves our network and returns an error to the sandbox. Stale placeholders never hit the upstream.

Limits

  • Up to 20 active credentials per vault (archived credentials don't count).
  • metadata on vaults and credentials: max 16 key-value pairs; keys ≤ 64 chars, values ≤ 512 chars.
  • Credentials are re-resolved on every chat turn — the lower bound on rotation latency is roughly one turn.
  • OAuth access tokens are refreshed automatically when within 60 seconds of expiry, or on a single upstream 401.

More resources

Security & limits - 21st Agents SDK Docs