Skip to main content
Credential injection lets a Sailbox call an API with a key it never sees. You store an API key with Sail, write an egress policy rule that says which HTTPS host gets it, and give the policy to a Sailbox. Code inside sends a normal request with no credential, and Sail adds it on the way out. Nothing on the Sailbox, including an agent running there, can read the key.

Try it

This stores a secret, injects it as a bearer token on requests to httpbin.org, and asks httpbin to echo the request back. Save the policy as demo.json:
demo.json
Then store the secret, save the policy, give it to a Sailbox, and make a request from inside:
Output
The curl inside the Sailbox never saw the token. Only the request that httpbin received included it. The same flow from the SDKs, with a GitHub token:

Secrets

A secret is a named value that belongs to your organization. Egress policies insert secrets into requests, and registry logins use them to pull private images.
Setting a name that already exists replaces its value. The next matching request from any Sailbox whose policy uses it gets the new value. Names start with a letter or digit and may contain letters, digits, _, and -, up to 128 characters. A value is non-empty text up to 64 KiB. It may span lines, as a PEM key does, but cannot contain tabs or other ASCII control characters.

Policies

A credential is added by a rule in an egress policy. The rule specifies the host, optionally narrows the requests it applies to, and sets a header, query parameter, or body field to ${secrets.NAME}. The reference has the full document format.
  • Only a saved policy may reference a secret, and the secret must exist before the policy is saved. A document passed straight to a Sailbox cannot use one.
  • Use an exact host. A wildcard such as *.example.com sends the credential to every host it matches.
A saved policy can also include an allowlist, so one policy limits a Sailbox to the hosts it needs and adds their credentials. A saved policy’s document cannot be edited. To rotate which hosts get a credential, save a new policy and set it. To rotate the credential itself, set the secret again.

Clients that need a key

Some clients refuse to start without an API key in the environment, or read the key themselves to build the request. For these, the policy’s env gives every command in the Sailbox a placeholder in place of the key, and a request.replace rule swaps it for the real key on the way out:
Inside the Sailbox, $OPENAI_API_KEY holds a value like sail_ph_3kTq9.... The OpenAI client sends it as Authorization: Bearer sail_ph_3kTq9..., and the request reaches api.openai.com with the real key. The placeholder is useless anywhere else: Sail refuses a request that carries it in a field the policy does not name, so code in the Sailbox cannot move it into a URL or another header to get the key sent somewhere unexpected. An agent that acts for several people can hold a key for each of them. Give each key its own env variable, and map the header to a list of the secrets, as in "authorization": ["NOTION_ALICE", "NOTION_BOB"]. Sail sends the key whose placeholder the request carries. See Several keys for one host for a full policy. For a client that checks the shape of a key, choose the placeholder’s start with {"secret": "OPENAI_KEY", "placeholder_prefix": "sk-"}. See Environment variables for the full rules.

AWS and S3-compatible storage

AWS and S3-compatible storage do not take a key in a header. The client uses its secret key to sign each request, so there is no field for a rule to fill in. For these, name a cloud identity in the policy, and Sail signs the request on the way out:
A client will not send a request until it has keys to sign with, so give the Sailbox placeholders. Sail discards the placeholder signature and signs again with the real key:
For AWS itself you can skip the stored key. Create a role that trusts your Sailboxes, as in Identity tokens, and name it in an aws identity:
Sail gets short-lived keys for the role and signs with them. The Sailbox still sends placeholder keys and never holds real ones. Ordinary SDK and CLI calls work this way. A few uncommon things do not, such as presigned URLs: see what does not work. To give code in the Sailbox its own short-lived credentials for AWS, Google Cloud, or another service that accepts OpenID Connect tokens, see Identity tokens.

Private servers and client certificates

tls_config connects to a host that uses a private certificate authority, or that asks for a client certificate (mutual TLS). Store the client certificate’s private key as a secret, then name it in the policy:
Code in the Sailbox connects to https://mtls.example.com as usual. Sail checks the server against trusted_cas and presents the client certificate, and the private key never enters the Sailbox. See TLS settings for each field.

Giving a Sailbox the policy

Give the same saved policy to as many Sailboxes as you like.
A set replaces the Sailbox’s whole policy and applies to connections opened after the call. See Replacing the policy for what already-open connections see.

Where secrets live

Secrets are stored by Sail and added as the request leaves the Sailbox. Nothing inside the Sailbox ever sees the value, and no Sail API returns it: sail secret show and sail secret list print names and timestamps only.
Output
To remove a secret, replace the policy on every Sailbox that uses it, delete every saved policy that names it, then delete the secret. Sail refuses the other orders. sail egress-policy list shows how many Sailboxes use each policy and which secrets it names.

Limitations

Rules apply to HTTPS only. They can change JSON and form request bodies up to 8 MiB, but not other bodies or responses. The reference lists every limit.