Runtime Vault

Runtime Vault stores values that bots may need during execution: service tokens, MCP server credentials, repository credentials, customer-specific API keys, or configuration that should not live in a bot workspace.

Use provider credentials for Botyard-managed provider calls. Use Runtime Vault when the bot or an MCP server needs an application secret at runtime.

Create a Runtime Vault variable

1. Sign in to app.botyard.io.
2. Open User menu › Settings › Credentials › Runtime Vault.
3. Click Add variable.
4. Enter a dot-delimited Key path, a Display name, an optional Description, and the Value. Values can span several lines, so PEM keys and service-account JSON paste intact.
5. Choose whether the value is a Sensitive value, and which bots may request it.
6. Optionally open the advanced settings to change Max TTL (seconds) or turn on Auto-delete after a period. The defaults suit most variables.

The key path is the stable reference bots and MCP templates use, for example github.tokens.read_only or mcp.snowflake.client_id.

Policy controls

Each Runtime Vault variable has a policy:

Max TTL and Auto-delete are separate. Max TTL caps how long each lease stays usable, and the variable itself stays in the vault. Auto-delete sets when the variable itself expires. Once that time passes, bots can no longer see or lease it, and Botyard deletes the value the next time a bot asks for it. A bot that asks for an expired variable gets a secret_expired error that tells it to request the value again. To keep a variable that is about to expire, edit it and turn Auto-delete off or set a new period.

Secrets are encrypted with the same per-organization age/X25519 storage model used for provider credentials. Plaintext values are not returned by the API after creation or update.

How bots obtain secrets

Runtime Vault uses short-lived leases:

1. A bot requests a lease for a key path and provides a justification.
2. Botyard checks the secret policy for that bot.
3. If allowed, Botyard creates a lease with a bounded TTL and maximum redemption count.
4. The bot receives an opaque secret reference, not the plaintext value.
5. The runtime redeems the lease when the value is actually needed.
6. Redemption decrypts the value, records the access, and marks one redemption as used.

This separates authorization from plaintext delivery. A bot cannot mint a lease for another bot's unshared secret, and an expired or already-used lease cannot be redeemed again.

When a bot asks you for a secret

A bot that needs a credential it doesn't have shouldn't ask you to paste it into the chat. It sends a secret request instead, which appears in the conversation as a form card. The bot fills in everything about each secret (key path, display name, description, max TTL, and optionally an auto-delete period). You type only the value.

1. Check the key paths. You can change them before submitting.
2. Type each value. Fields for sensitive values are masked.
3. Submit. One request can ask for several secrets, and they are saved together or not at all.

The values go straight into the Runtime Vault. They are never written into a message or a log, and the bot gets only the key paths back. Each new secret is linked to the bot that asked, so it can lease it straight away. A request can also ask to replace the value of a variable the bot already uses; the card marks that secret as replacing an existing one. Any signed-in person with access to the conversation can fill in the request. API keys can't. Sharing the secrets with other bots, or with every bot, requires the organization owner role.

Secrets created by bots

Bots can also create Runtime Vault variables themselves, for example to store a token they minted. Such a variable records the bot that created it and is linked only to that bot by default. A bot can update only variables it created. Nobody, bot or person, can create variables under Botyard's reserved key path prefixes: credentials., composio_connections., and integration_logins.. These variables appear in the Runtime Vault tab like any other, and their access can be changed there.

To see or change which variables a specific bot may use, use the bot-scoped endpoints GET /v1/orgs/{org_id}/bots/{bot_slug}/vault-entries and PUT/DELETE /v1/orgs/{org_id}/bots/{bot_slug}/vault-entries/{entry_id} in the API reference.

MCP server secret references

MCP servers can reference Runtime Vault key paths in three places: environment variables (env_secret_refs), secret files (secret_file_mounts), and request headers (secret_headers). The examples below use environment variables.

For example:

{
  "env_secret_refs": {
    "SNOWFLAKE_CLIENT_ID": "mcp.snowflake.client_id"
  }
}

When an MCP server is provisioned, Botyard resolves the key path through the secrets service instead of storing the plaintext in the MCP template. That lets an organization rotate the vault value without editing every template that references it.

Use env_secret_refs for durable MCP credentials. Use pasted plaintext only for non-sensitive or one-off setup values.

Who may add a secret reference

A running MCP server receives its referenced secrets with organization scope, so adding a reference is effectively granting that server the secret. The rules depend on who makes the change:

• People and API keys in the organization can reference any organization vault variable.
• Bots can only add a reference (in env_secret_refs, secret_file_mounts, or secret_headers) to a variable they could lease themselves. That means Allow all bots is on, or the bot is a linked bot, and the variable has not expired. Otherwise the change is refused with the standard "This secret is not available to this bot." error. The error is the same whether the variable is missing, unlinked, or expired.

A bot's change is checked only for references it adds. It can still edit other fields, or rename an environment variable that points at a secret the server already receives, without being linked to that secret.

The check runs when the server is created or updated. It is not re-evaluated later: unlinking a bot or turning off Allow all bots afterwards does not remove references that are already saved. To revoke a server's access, edit or delete the server's references.

Safety pattern

Runtime Vault follows a brokered secret access pattern with just-in-time leases:

• the policy decides which bots may request a secret
• the lease limits how long a grant is useful
• redemption limits how often it can be used
• audit events record lease requests, grants, denials, use, revocation, and expiry, plus changes to a variable's value or TTL
• sensitive values are included in exfiltration scanning

This gives bots access to credentials without making the workspace a permanent secret store.

Related docs

• Exfiltration scanning

• Audit logs

• MCP setup templates

• Manage Botyard with Terraform to declare vault secrets as code

For a product overview, see Runtime Vault on botyard.io.