Advanced: Credential Vault Security and the Egress Gateway

​

Overview

​

Who should read this

• Your agent calls external APIs at runtime (your own services, third-party SaaS) and needs an API Key / Token;
• You do not want secrets in cleartext in: application code, agent configuration and version history, the sandbox process, the model context, or event-stream logs;
• You are running a security or compliance review and need to explain precisely where secrets live along the chain.

​

The model: placeholder injection

​

Gateway behavior boundaries

​

Two injection paths: a layered choice

​

Prerequisites

• A Bailian workspace and its ID, one DashScope API Key;
• an agent with the bash tool (bash enabled in the built-in toolkit's configs[] — see the getting-started page);
• an external echo service for verification (this page uses httpbin.org — its /get endpoint echoes your request headers back, perfect for observing "what did the other side actually receive").

export AGENTSTUDIO_URL="https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio"
export DASHSCOPE_API_KEY="<your DashScope API Key>"
export AGENT_ID="agent_xxx"          # the agent with bash
export MY_API_KEY="sk-DUMMY_KEY_FOR_SMOKE_TEST"   # a dummy value for the demo

​

Step 1 · Create the vault

curl -X POST "$AGENTSTUDIO_URL/vaults" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "生产环境密钥库",
    "metadata": { "team": "operations" }
  }'

export VAULT_ID="vlt_xxx"

​

Step 2 · Create the credential: allowed_hosts required

curl -X POST "$AGENTSTUDIO_URL/vaults/$VAULT_ID/credentials" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "天气服务 API Key",
    "auth": {
      "type": "environment_variable",
      "secret_name": "MY_API_KEY",
      "secret_value": "'"$MY_API_KEY"'",
      "networking": { "allowed_hosts": ["httpbin.org", "*.httpbin.org"] }
    }
  }'

• secret_name: the environment variable name; os.environ in the sandbox reads the placeholder by this name.
• secret_value: the real secret. Write-only — GET returns only secret_name / type / networking in auth.
• networking.allowed_hosts: the egress whitelist, required. Wildcards supported (*.example.com). This is "declare at configuration time, once, which domains the secret may travel to".
• networking.type: optional (limited is also accepted); behavior is governed by allowed_hosts.
• The response id is prefixed vcrd_ (not cred_).

export CRED_ID="vcrd_xxx"

​

Step 3 · Attach the vault to a session

curl -X POST "$AGENTSTUDIO_URL/sessions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "'"$AGENT_ID"'",
    "title": "密钥注入验证",
    "vault_ids": [ "'"$VAULT_ID"'" ]
  }'

​

Step 4 · Verification one: only a placeholder in the sandbox

curl -X POST "$AGENTSTUDIO_URL/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      { "type": "message", "role": "user",
        "content": [ { "type": "text", "text": "Run exactly this bash command and report the raw output verbatim, nothing else: printenv MY_API_KEY" } ] }
    ]
  }'

{"stdout":"BMA_SECRET_PLACEHOLDER_MY_API_KEY\n","stderr":"","exit_code":0,"interrupted":false}

​

Step 5 · Verification two: egress requests substituted by the gateway (the happy path)

curl -X POST "$AGENTSTUDIO_URL/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      { "type": "message", "role": "user",
        "content": [ { "type": "text", "text": "Run exactly this bash command and report the raw output verbatim, nothing else: curl -sk --max-time 30 -H \"Authorization: Bearer $MY_API_KEY\" https://httpbin.org/get" } ] }
    ]
  }'

{
  "headers": {
    "Authorization": "Bearer sk-DUMMY_KEY_FOR_SMOKE_TEST",
    "Host": "httpbin.org",
    ...
  },
  "origin": "39.105.83.17"
}

​

The negative path: a non-whitelisted host

{
  "headers": {
    "authorization": "Bearer BMA_SECRET_PLACEHOLDER_MY_API_KEY",
    "host": "postman-echo.com",
    ...
  }
}

​

Egress TLS validation: passes by default

• curl with default validation → exits 0 normally;
• Python requests (default verify=True) → HTTP 200 normally;

​

Step 6 · Session environment variables: first choice for non-sensitive config

curl -X POST "$AGENTSTUDIO_URL/sessions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "'"$AGENT_ID"'",
    "environment_id": "'"$ENV_ID"'",
    "title": "客户咨询 #1234",
    "environment_variables": {
      "API_BASE_URL": "https://new.example.com",
      "LOG_LEVEL": "info"
    }
  }'

• printenv API_BASE_URL in the sandbox → https://new.example.com (the real value, directly usable by the agent's bash / python);
• the creation response and GET /sessions/{id} both echo the field verbatim (sibling of metadata) — note this makes it visible to anyone with session read access; keep it non-sensitive;
• Deployment does not support it: passing environment_variables to POST /deployments does not error but is silently ignored — the generated sessions have none. Scheduled pipelines must use vault_ids.

​

Step 7 · Operations and cleanup

• Rotation: the vault API has no dedicated rotation endpoint; updating secret_value directly is the current method (the update must carry the full auth value).
• Cleanup order: delete the credential (child) before the vault (parent) — deleting a vault does not cascade to its credentials (orphan data); the full lifecycle verb matrix is in the production page.
• The Webhook side exposes vault.created / archived / deleted and vault_credential.created / archived / deleted events for control-plane monitoring — see Advanced: Webhook Event Notifications.

​

FAQ

​

Summary

• The placeholder model: secrets live only in the credential store (encrypted); the sandbox, the model context, and platform events see only BMA_SECRET_PLACEHOLDER_*; the real value appears only in the Authorization header at the egress instant, for a host matching allowed_hosts. Content echoed back in external service responses (e.g. httpbin) is outside this guarantee.
• The gateway substitutes only the Authorization header, matched only by host: other headers pass through unsubstituted; non-whitelisted requests flow as usual but the secret stays home.
• One credential per host: multiple credentials on one host make substitution ambiguous.
• TLS: sandbox egress goes through gateway MITM, but the gateway CA is preinstalled and default validation passes; investigate CA variables on certificate errors instead of disabling validation routinely.
• Layered choice: non-sensitive config via session environment variables (cleartext); high-sensitivity secrets and Deployment unattended pipelines via the vault.

​

Next steps

• Credentials: vault and credential operations in the console.
• Advanced: Productionize a Morning-Briefing Robot: vault_ids wiring on deployments.
• Credential API: full parameters of the credential endpoints.