Secrets

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 and your own model provider key.

Create a secret

albus secrets create github-mcp --value "Bearer ghp_…"

# 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

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_…")

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_…" }'

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:

{
  "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.

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").

Inspect, rotate, delete

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.

Getting started

Guides

For coding agents

Alpha

Reference

API reference

Create a secret

Reference a secret

Inspect, rotate, delete

​Create a secret

​Reference a secret

​Inspect, rotate, delete

Create a secret

Reference a secret

Inspect, rotate, delete