Skip to main content
An agent refers to a credential by name. A skill credential is added to the skill call at the moment of use, so the agent never holds it. Three kinds are environment variables in the agent’s workspace, which code the agent runs can read: workspace secrets, the Vault secrets bound to the agent, and a person’s own credentials bound to the agent. A person’s own credentials reach only that person’s turns.

Where credentials live

Your own credentials

When you connect a skill with Personal access, your credential is stored in the Vault under your name, used for your requests only, and never shown again. If a skill requires each person’s own sign-in, xpander asks you the first time the agent needs it. The agent then acts with your permissions where systems allow. To connect ahead of time, open Settings > My tools. Each app shows whether you are connected or need to sign in, and Sign in connects you once for every agent and AI tool. Apps that take keys also offer Use a token, and the Keys tab holds the tokens you pasted. See My tools. You hold one personal connection per skill. Connecting again reuses it, and a new credential replaces the old one. Only organization admins add a shared connection or share a personal one with the organization. Rotate an expiring credential in Settings > My tools (Keys > Replace token). The next conversation uses the new value.

What an agent declares

An agent can declare the secrets it needs, such as GITHUB_TOKEN. Declarations are kept in its version history with its skills and instructions, so teammates see what it needs before running it.
Use Per user scope for anything that acts in a person’s name (source control, calendars, ticketing) and Shared for service accounts and third-party API keys. Keep the names vendor command-line programs expect, such as GITHUB_TOKEN and GITLAB_TOKEN.Each requirement shows Satisfied for everyone (a shared secret is bound), Satisfied for you (your credential is bound) or Missing (the agent asks when it needs it). A Vault secret bound under the variable name an agent reads satisfies a shared requirement, so one entry can serve two agents under different names. Each name is exported once, so a second secret under a used name is refused. The agent owner never binds a personal credential for someone else.The per-agent Secrets section, where an owner reviews declared requirements and binds Vault entries to the agent by hand, is not switched on in every organization yet. Where it is off, the Vault’s access levels, the secret card and workspace secrets are how an agent gets its values, and the secret card makes the bindings described here.

Workspace secrets on an agent

Open the agent’s workspace, choose Workspace settings from its menu, then the Secrets view.
  • Key: uppercase letters, digits and underscores. Runtime-reserved prefixes are refused.
  • Value: a literal, or an external-vault reference written as ${ext:NAME}, pulled when the workspace starts.
The agent reads its secrets fresh each turn, so changes need no restart. In Agent settings, the agent’s own secrets are under Advanced > Vault secrets (Manage secrets); the agent reads each as $NAME and cannot add or change them. Group toggles in Platform > Organization > Members & groups decide who sees workspace secrets at all.
Any program the agent runs in its workspace can read its secrets, including code from a pull request it checks out and tests. Give an agent that runs untrusted code only the secrets that code may see.

When a secret is missing

The agent asks with a secret card (Ask for secret) in the conversation, or a single-use link to a Provide secrets page. The card names the secret, says what it is for and offers a masked field. The value goes straight to the Vault or the workspace, never to the model or the transcript. The agent continues on its next turn. A matching entry you already hold satisfies the requirement, and no card is raised.
For each name the card reports saved and bound, saved but not bound, or not saved, and a Saved chip confirms what was stored. An agent can also see the names, never the values, of Vault secrets not yet bound to it, and send you a link to bind one.

Which value wins

  1. Your personal credential
  2. A secret bound to the agent
  3. The agent’s workspace secrets
A secret can never override variables the runtime owns. For admins: adding Vault secrets, attaching an external vault, which secrets reach an agent and what is recorded are on Vault.

Next steps

Manage the Vault

Secrets, external vaults and audit.

Govern every agent

Organization controls.