Add an HTTP secret

Let your agent call any HTTP API with a real key that it never sees. Your agent needs the OpenAI API, a Stripe test key, or your internal service’s token. You save the key once as an HTTP secret. The agent gets a placeholder in an environment variable and uses it like the real key. On the way out, Marshal swaps the placeholder for the real value, and only on requests to the hosts you list.

Before you start

Any member can create an HTTP secret.
You have the key and you know which hosts it is for, for example https://api.openai.com.

Create the secret

In the left rail, open Connections.
On the HTTP Secret card, click Connect. If you already have one, the button says Add another.
In New HTTP secret, enter a Name, for example “OpenAI API”.
Enter the Env var, for example OPENAI_API_KEY. Use capital letters, digits, and _, starting with a letter. You cannot change it after you create the secret.
Under Secret value, paste the key. If you already saved the value as a credential, choose Saved credential instead of Paste value.
Under Hosts, enter at least one URL pattern the key is for, for example https://api.openai.com/**. Click + host to add more. Each pattern starts with https:// or http://, then a host. In the host, * matches one label and ** matches across dots, as in https://*.example.com. In the path, * matches one segment and ** matches the rest. A port, when you give one, is a number. Marshal checks every pattern when you save, and the message names the pattern to fix, for example host "OPENAI_API_KEY": missing scheme.
If an Owner field is shown, choose who owns the secret: Just me, a team, or Everyone in the organization. The owner decides whose spaces can use it.
Optional: open Advanced to set a Placeholder prefix and Total length. Use them when a tool checks the shape of the key, for example that it starts with sk-.
Click Create.

Use it in a space

Open a running space and open the right panel (Toggle inspector panel in the toolbar).
Open the Secrets tab.
On your secret, click Add. It changes to Active. The space does not restart. A space can hold one secret per env var. If another secret with the same env var is already Active, Marshal declines the Add and names both secrets. Remove the active one first, then add the other.
In a terminal that was already open, reload the environment:
```
source /run/agent-env
```

New terminals see the variable at once. The placeholder is also written to ~/workspace/.env.marshal, for tools that read a .env file. To take the secret out of the space, hover over Active and click Remove.

Your administrator can set a stack to add HTTP secrets to new spaces on their own.

How the swap works

The agent sees only the placeholder. The real value stays outside its reach.
Marshal swaps the placeholder in the URL, the query string, the headers, and JSON or form bodies.
The swap happens only for the hosts you listed. A request that carries the placeholder to any other host is blocked.

What you should see

The secret on the Connections page under HTTP Secrets.
In the space’s Secrets tab, the secret marked Active, and the note “Placeholder env vars are written to: ~/workspace/.env.marshal”.
In the space, echo $OPENAI_API_KEY prints the placeholder, not your key. A call to the API with it works.

Ask your agent to use the API, for example “Call the OpenAI API with $OPENAI_API_KEY and list the models.”