# Secrets

A secret holds a credential, such as an API key, for your organization. A computer that binds it gets a placeholder in the same format, and the proxy puts the real value into requests to the hosts the secret allows. By default, a binding gives the computer only the placeholder.

## Bind a secret

Create a secret once with `secrets().create`, giving its value and, in `allow`, the hosts the value may be sent to. Then bind it to a computer in `secrets`, under the environment variable agents will read:

```rust
let binding = SecretBinding::Ref {
    key: "OPENAI_API_KEY".parse()?,
    secret: "openai".parse()?,
    file: None,
    reveal: false,
};
```

Every new process on the computer sees `OPENAI_API_KEY`, set to the placeholder.

## How the proxy uses it

The placeholder has the real value's format, so client libraries accept it. When it appears in an HTTPS request on port 443 to a host that both the secret's `allow` and the computer's network policy permit, the proxy puts the real value in its place. It looks in headers, the path and query, Basic credentials, form fields and JSON strings.

Anywhere else, the placeholder is sent unchanged: in a request to another host, in a compressed body or in a body over 1 MiB.

A placeholder stays the same when you rotate the secret, so computers keep working with the new value.

:::note
`allow` only says where the value may go. Whether the computer can connect to that host at all is up to its [network policy](/computer/concepts/networking).
:::

## When the computer needs the real value

Some uses need the value itself inside the computer: signing requests (AWS SigV4, HMAC), client certificates and SSH keys, protocols other than HTTPS, and clients that check a token's expiry. For those, bind the secret with `reveal: true`.

The proxy does not change responses, so an API that returns a credential returns it to the computer.

## Next steps

* [Networking](/computer/concepts/networking): choose where computers can connect
* [Extensions](/computer/concepts/extensions): answer calls from your own code instead of the computer