Skip to main content
Platform > Agents > Secrets is the Vault: every credential in the workspace, in one list. An agent references a credential by name. A skill credential is added to the call at the moment of use, so the agent never holds it. A secret bound to the agent is an environment variable in its workspace, which code the agent runs can read. How agents and people use credentials (personal connections, workspace secrets, the secret card) is on Credentials. The Vault holds environment secrets (single-line values), environment files (multi-line) and credentials shared across the organization. Values are encrypted and never shown again. A secret bound to an agent reaches it as an environment variable at run time. Agents never see the Vault itself.

Add a secret

Click Add secret and fill in:
  • Secret name: saved in uppercase and underscores, for example STRIPE_API_KEY. Agents read it under this name. Names xpander reserves are refused.
  • Type: API key or token for a single-line value (one environment variable), or Multi-line text for a private key, certificate or config file (a file, line breaks kept).
  • Value: usable once saved, never shown again.
  • Who can use it: Everyone, Groups and people (plus admins) or Owner only (you and organization admins).
  • Variable name (optional): the name agents read, if it should differ from the secret name.
Bulk add imports several at once, for example from a .env file.
Add secret panel with Secret name, Type (API key or token, Multi-line text), Value, Who can use it (Everyone, Groups and people, Owner only) and Variable name

Add secret: name, type, value, who can use it and an optional variable name. Shown with sample data.

Manage a secret

Each row shows the secret’s type, its owner (You or the person’s name; organization secrets name nobody), its location, who can use it and Last used. Not recorded means no use is on record yet; Not tracked marks credentials whose uses are not recorded, such as a skill’s, a bot’s or a model provider’s. Narrow the list with Type and Owner. Each row’s menu offers Replace value (overwrites, never reveals), Manage access, Attach to agent and Delete (agents using it stop receiving it). Admins always keep access. Each secret lives in one storage location: the xpander vault or an attached vault. Select a secret to open its card: Last used, Used by (the agents it is attached to; agents can also get a secret without being attached, so the list may be incomplete), Access, Updated, and Activity, each use with who or which agent used it. Values are never logged.

Attach a secret to an agent

Attach to agent, in the row’s menu or on the secret’s card, binds the secret to an agent you can edit. Pick the Agent and the Environment variable it reads the value under. Tick Only for me to give the value only to your own conversations with that agent; off, everyone who runs the agent gets it. The agent then appears under Used by. Attach to agent shows unless every group you are in turns off Agent secrets (under Agent settings) in Platform > Organization > Members & groups. Credentials other settings own also appear here: skill sign-ins, messaging bot credentials, the SSO client secret, organization API keys, webhook secrets and model provider keys. A Manage action opens the tab that owns them. Provider keys live under Platform > AI governance > Models, and the runtime’s model proxy holds them, never an agent’s workspace.

Attach an external vault

xpander can import secret names from a vault your organization already runs and leave the values there. Values are pulled at use time, and ${ext:NAME} in an agent’s workspace secrets pulls a value when the workspace starts. Supported today: Azure Key Vault.
  1. Click Storage locations, then Attach vault. The built-in xpander vault is the default for new secrets.
  2. Enter the vault URL, tenant ID, the client ID and client secret of a service principal with the Get and List secret permissions, an optional expiry date for that secret, a display name, and whether to Use this vault for new secrets.
  3. Click Connect and import names. Names are imported with access off until you grant it.
Secrets page with the Storage locations panel open, listing xpander vault marked Default and an Attach vault button

Storage locations: the built-in xpander vault, the default for new secrets, and Attach vault. Shown with sample data.

Attach Azure Key Vault panel with Vault URL, Tenant ID, Client ID, Client secret, Credential expires on, Display name and Use this vault for new secrets, filled with sample values

Attach Azure Key Vault: vault URL, tenant ID, client ID and secret, optional expiry and display name, and whether new secrets go to this vault. Shown with sample data.

The vault’s menu offers Refresh secret names (re-imports names), Update credential (after you rotate the secret in Entra) and Detach vault (removes the imported names without touching the vault). The expiry date lets the Vault warn you before the credential lapses.

Which secrets reach an agent

Every use of a secret is a use_secret event in Platform > AI governance > Audit log, so you can see which agents still rely on the whole set and bind their secrets directly. Workspace secrets and external vault references are unaffected. On agents that run on Claude Code, Codex or OpenCode, the value of a secret the agent received (8 characters or longer) shows as *** in the run’s activity, streamed text and result.

What is recorded

Platform > AI governance > Audit log, Vault category, records each change by name, never by value, with who did it. A .env import is one entry naming the secrets added. Who sees workspace secrets on an agent at all is a group toggle in Platform > Organization > Members & groups.
Secret Created, Secret Updated, Secret Deleted, Secret Read, Secret Used, Secret Moved to Vault, Workspace Secrets Updated and LLM Secrets Changed.

xpander’s keys on a self-hosted cluster

Provider keys and xpander’s own secrets are Kubernetes secrets in the release namespace: Skill credentials, skill OAuth tokens and IAM session credentials stay in your cluster. The skill relay injects them at call time. Per-person MCP sign-in tokens stay in your cluster on Air-Gapped. On Hybrid they live in xpander Cloud’s vault and are fetched at run time (details). Skills that reach AWS can use AWS Secrets Manager.

Next steps

Understand how agents use credentials

Connections, workspace secrets, the secret card

Manage LLM API keys on Hybrid

Chart values to secrets