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

# Secrets

> Store credentials in your organization and reference them from an agent configuration.

An agent configuration is stored and versioned, so it must never contain a raw
credential. Instead you store the credential once as an organization secret and
put a **reference** to it in the configuration. Albus resolves the reference at
launch; the value is never returned by the API and never appears in a session,
audit event, or agent revision.

You need secrets for two things: [MCP server headers](/guides/mcp-servers) and
[your own model provider key](/guides/model-providers).

## Create a secret

<CodeGroup>
  ```bash CLI theme={null}
  albus secrets create github-mcp --value "Bearer ghp_…"
  ```

  ```bash CLI (stdin) theme={null}
  # Keeps the value out of your shell history and process list.
  printf 'Bearer ghp_…' | albus secrets create github-mcp
  albus secrets update github-mcp < new-value.txt
  ```

  ```python Python theme={null}
  import os
  from albus_sdk import Albus, models

  with Albus(
      security=models.Security(api_key_auth=os.environ["ALBUS_API_KEY_AUTH"]),
  ) as albus:
      albus.secrets.create_secret(name="github-mcp", value="Bearer ghp_…")
  ```

  ```bash cURL theme={null}
  curl --fail-with-body --request POST https://albus.sh/api/secrets \
    --header "Authorization: Bearer $ALBUS_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{ "name": "github-mcp", "value": "Bearer ghp_…" }'
  ```
</CodeGroup>

Names are path-like: `/`-separated segments of `[a-zA-Z0-9_-]`, up to 255
characters total, no empty, `.`, or `..` segments. Group related credentials the
way you would in a filesystem:

```
github-mcp
integrations/github/token
providers/gemini/prod
```

## Reference a secret

A reference is the secret's name under `albus.sh/secrets/`:

```
albus.sh/secrets/integrations/github/token
```

Use it wherever a credential belongs:

```json theme={null}
{
  "model": {
    "name": "gemini-3.6-flash",
    "provider": {
      "name": "gemini",
      "credential": "albus.sh/secrets/providers/gemini/prod"
    }
  },
  "mcp_servers": [
    {
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "albus.sh/secrets/integrations/github/token" }
    }
  ]
}
```

A reference to a secret that does not exist fails the run with `400` before the
agent starts, so a typo costs you nothing but the error.

<Note>
  `model.provider.credential` **must** be a reference — a raw key there is
  rejected. MCP `headers` accept either: a value in reference form is resolved, and
  anything else is sent literally (`"X-Api-Version": "2024-01-01"`).
</Note>

## Inspect, rotate, delete

```bash theme={null}
albus secrets list
albus secrets get github-mcp     # metadata and a masked value
albus secrets update github-mcp --value "Bearer ghp_new…"
albus secrets delete github-mcp
```

Reads return the value masked to its last three characters — there is no
operation that returns a secret's value. Rotating is an `update`: references keep
working and the next run picks up the new value, with no agent configuration
change and therefore no new revision.