Credential Vault

​

Structure

• Vault: A container for grouping and managing credentials.
• Credential: A specific secret stored within a vault, consisting of a variable name and its corresponding value.

​

Creating a Vault

1. On the Credentials page, click Create Vault.
2. Enter a vault name and click Create.

​

Adding Credentials

1. Click the vault name to navigate to its detail page.
2. In the Credential List section, click New Credential.
3. Fill in the following fields:
   • Name: A display name for the credential.
   • Type: Fixed to Environment Variable. The credential is referenced as an environment variable by the agent and replaced with the real value by the gateway at egress.
   • Variable Name: The key used by tools to reference this credential (e.g., MY_API_KEY). Cannot be changed after creation.
   • Variable Value: The actual secret value. After saving, the console and API display only the last 4 digits; the plaintext is never returned, and the value is decrypted and injected server-side only when referenced by tools.
   • Injection Location: Fixed to Authorization header (Bearer). The real credential is written into the request's Authorization header as Bearer <secret>. Placeholders in the request body and query parameters are not replaced.
   • Allowed Hosts: Restricts which hosts receive the real credential—only requests sent to these hosts have the placeholder replaced; all other hosts only see the placeholder. Separate entries with commas or newlines, support *.example.com wildcard subdomains, up to 10 hosts. Enter * to apply to all hosts; acknowledge the risk and confirm.
4. Check the shared credential acknowledgement, then click Create to complete.

​

Credential Injection Mechanism

1. Placeholder reference: The agent references the credential via the ${VARIABLE_NAME} environment variable in tool or MCP code. For example, writing Authorization: Bearer ${MY_API_KEY} in the Authorization header.
2. Gateway rewriting: At egress, the gateway checks whether the target host is in the Allowed Hosts list. On a match, it replaces the placeholder in the Authorization header with the real credential; on no match, it leaves the placeholder as-is, so the target host only receives the placeholder.
3. Scope: Only placeholders in the Authorization header are replaced; placeholders in the request body and query parameters remain untouched.
4. Host matching rules: Exact and wildcard matching; matching is case-insensitive and ignores ports; *.example.com matches its subdomains but not the bare domain example.com — list the bare domain separately.
5. Redirect safety: If a request is redirected (3xx) across domains to a host outside Allowed Hosts, the redirected request is not replaced.

​

Choosing Allowed Hosts

• * (open): Requests to all hosts are replaced with the real credential, for workloads that don't need to restrict where the credential is sent. Acknowledge the risk and confirm.
• Specific hosts (restricted): e.g. api.example.com, *.example.com. Only requests to matching hosts receive the real credential; all others receive the placeholder, which contains no credential value, so a leaked placeholder does not expose the credential. For cases where the credential should only reach your own services.

​

Referencing Credentials in Code

import os, requests

# What you read is a placeholder; no need to know the real value
token = os.environ["MY_API_KEY"]
requests.get("https://api.example.com/v1/data",
             headers={"Authorization": f"Bearer {token}"})

​

Difference from Environment Variables

• When using a third-party SDK or skill whose underlying request authentication cannot be confirmed, the gateway cannot guarantee replacement at the correct location — use session environment variables instead.
• The real value of a session environment variable can be read or printed by code in the container and may enter logs and model context; use a vault for highly sensitive credentials.

​

Binding to a Session

​

Next Steps

• Initiate a Session: Bind a vault when creating a session.
• Define an Agent: Attach MCP services or skills requiring authentication to your agent.