> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superlog.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace secrets

> Let agents call your APIs with credentials they never see.

Workspace secrets let an agent call an API that needs a credential, such as an internal service or a provider without a built-in integration, without exposing the credential to the agent.

## How secrets work

1. You store a secret with a name, a value, and a list of allowed hosts.
2. When a run uses the secret, the sandbox gets an environment variable with the secret's name. Its value is a placeholder, not the real credential.
3. When the agent sends a request to an allowed host, Superlog replaces the placeholder with the real value at the network boundary. Requests to other hosts keep the placeholder.

The real value is never readable in the sandbox, in the transcript, or in the app after you store it. Superlog also blocks placeholders from appearing in pull requests, commit messages, and reports.

## Create a secret

<Steps>
  <Step title="Open the secret dialog">
    Open `/agents/new` in Superlog. In the **Workspace secrets** panel, click **Add secret**.
  </Step>

  <Step title="Name it">
    Under **Environment variable**, enter the name, for example `METRICS_API_KEY`. Names use uppercase letters, digits, and underscores, up to 80 characters. Some names, such as `PATH` and `HOME`, are reserved.
  </Step>

  <Step title="Enter the value">
    Paste the credential under **Secret value**. Values can be up to 64 KB. You cannot view the value again after you store it.
  </Step>

  <Step title="Set the allowed hosts">
    Under **Allowed hosts**, list 1 to 20 hostnames, without a scheme, path, or port. A leading `*.` matches subdomains.

    ```text theme={null}
    api.example.com, *.example.net
    ```
  </Step>

  <Step title="Store it">
    Click **Store and add**. The secret is now available to every automation in the workspace and to tag mode.
  </Step>
</Steps>

<Warning>
  Allowed hosts are the boundary for the secret. List only the hosts the agent needs to call.
</Warning>

## Use a secret

* **Automations:** In the automation editor, click **Add connector** and pick the secret under **Workspace secrets**. An automation can use up to 20 secrets.
* **Tag mode:** In **Tag mode**, click **Choose secrets** under **Workspace secrets**.

Tell the agent in its instructions which variable to use and for what, for example: "Call `https://api.example.com/v1/status` with the bearer token in `$METRICS_API_KEY`."

## Rotate a secret

Secrets cannot be edited. To rotate a credential, create a new secret with a new name, select it in your automations and tag mode, and remove the old one from them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.