Skip to main content

创建 Credential

在指定 Vault 中创建一个 Credential。auth 当前仅支持 environment_variable 类型。secret_value 等敏感值仅写入时传入，响应中不返回。

前提

已完成 Endpoint 与鉴权配置，详见API 总览与认证。

接口

POST /vaults/{vault_id}/credentials

请求体

字段必填类型说明
auth是object认证信息，固定为 environment_variable 类型。
display_name否stringCredential 可读名称，最大 255 字符
metadata否object业务自定义键值对元数据

auth 类型

auth 当前仅支持 environment_variable 一种类型，以环境变量形式注入会话。
字段必填类型说明
type是string固定为 environment_variable
secret_name是string环境变量名称，需满足 ^[a-zA-Z][a-zA-Z0-9_]*$：以字母开头，仅支持字母、数字和下划线。创建后不可修改
secret_value是string环境变量值，仅写入时传入，响应中不返回
networking是object网络策略，限制只有发往指定域名的请求才会被替换为真实密钥
networking.allowed_hosts是array允许替换真实密钥的域名列表，支持 *.example.com 通配子域，最多 10 个。填 * 对全部域名生效
injection_location是object替换位置，标识密钥写入请求的位置。替换位置为请求头；请求体与查询参数中的占位符不会被替换
injection_location.header否boolean是否启用请求头替换，固定传 true
同一 Vault 内 secret_name 不能重复，否则返回 409 CREDENTIAL_SECRET_NAME_DUPLICATE「该Vault下已存在相同变量名称的凭证」。

请求示例 

curl -X POST "$AGENTSTUDIO_URL/vaults/vlt_xxx/credentials" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "第三方 API 密钥",
    "auth": {
      "type": "environment_variable",
      "secret_name": "API_KEY",
      "secret_value": "sk-xxxx",
      "networking": {
        "allowed_hosts": [
          "api.example.com",
          "*.example.com"
        ]
      },
      "injection_location": {
        "header": true
      }
    }
  }'

响应 

{
  "id": "cred_xxx",
  "type": "credential",
  "vault_id": "vlt_xxx",
  "display_name": "第三方 API 密钥",
  "auth": {
    "type": "environment_variable",
    "secret_name": "API_KEY",
    "networking": {
      "allowed_hosts": [
        "api.example.com",
        "*.example.com"
      ]
    },
    "injection_location": {
      "header": true
    }
  },
  "metadata": {},
  "archived_at": null,
  "created_at": "2026-07-10T08:00:00Z",
  "updated_at": "2026-07-10T08:00:00Z",
  "request_id": "req_xxx"
}

响应字段

字段类型说明
idstringCredential ID，格式 cred_xxx
typestring固定为 credential
vault_idstring所属 Vault ID
display_namestringCredential 可读名称
authobject认证信息，敏感值已脱敏（如 secret_value 不返回）
auth.typestring认证类型，当前仅支持 environment_variable
auth.secret_namestring环境变量名称
auth.networkingobject网络策略
auth.networking.allowed_hostsarray允许替换真实密钥的域名列表
auth.injection_locationobject替换位置。替换位置为请求头；请求体与查询参数中的占位符不会被替换
auth.injection_location.headerboolean是否启用请求头替换
metadataobject业务自定义键值对
archived_atstring | null归档时间，未归档时为 null
created_atstring创建时间，ISO 8601
updated_atstring最近更新时间，ISO 8601
request_idstring请求唯一标识

错误码

状态码错误码说明
400InvalidParameterRequired parameter missing or invalid.
401InvalidApiKeyInvalid API-key provided.
409CREDENTIAL_SECRET_NAME_DUPLICATEsecret_name 在该 Vault 内已存在。