创建凭证 - Qoder

POST /api/v1/cloud/vaults/{vault_id}/credentials 为指定 Vault 添加一个新的 MCP 服务器凭证。

请求头

头部	必选	说明
`Authorization`	是	`Bearer <PAT 或 SAT>`
`Content-Type`	是	`application/json`

路径参数

参数	类型	必选	说明
`vault_id`	string	是	Vault 的唯一标识符

请求体

字段	类型	必选	说明
`auth`	object	是	凭证鉴权信息。见 Credential auth object
`display_name`	string	否	兼容字段；当前响应固定为 `null`，不持久化
`metadata`	object	否	与 credential 一起存储的自定义元数据对象；省略时为 `{}`

请求示例

Static Bearer

curl -X POST "https://api.qoder.com/api/v1/cloud/vaults/vault_019e3bb940277f0db05ab74291acf6ef/credentials" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "type": "static_bearer",
      "mcp_server_url": "https://example.com/mcp-stream",
      "token": "your-access-token"
    },
    "metadata": {"team":"docs"}
  }'

导入 MCP OAuth token

已有 OAuth token 时使用该请求。需要浏览器交互授权时，请改用发起 MCP OAuth。

curl -X POST "https://api.qoder.com/api/v1/cloud/vaults/vault_019e3bb940277f0db05ab74291acf6ef/credentials" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "type": "mcp_oauth",
      "mcp_server_url": "https://mcp.example.com/mcp",
      "access_token": "oauth-access-token",
      "expires_at": "2026-08-16T08:00:00Z",
      "refresh": {
        "client_id": "oauth-client-id",
        "refresh_token": "oauth-refresh-token",
        "token_endpoint": "https://auth.example.com/oauth/token",
        "token_endpoint_auth": {
          "type": "client_secret_basic",
          "client_secret": "oauth-client-secret"
        },
        "resource": "https://mcp.example.com/mcp",
        "scope": "mcp.read mcp.write"
      }
    },
    "metadata": {"team":"docs"}
  }'

示例响应

HTTP 200 OK

{
  "id": "vcred_019e3bb98877759e862750b495c1fce8",
  "type": "vault_credential",
  "vault_id": "vault_019e3bb940277f0db05ab74291acf6ef",
  "auth": {
    "type": "static_bearer",
    "mcp_server_url": "https://example.com/mcp-stream"
  },
  "display_name": null,
  "metadata": {
    "team": "docs"
  },
  "archived_at": null,
  "created_at": "2026-05-18T15:34:35.387093Z",
  "updated_at": "2026-05-18T15:34:35.387093Z"
}

导入 mcp_oauth 后，响应会按同样规则脱敏：

{
  "id": "vcred_019e3bb98877759e862750b495c1fce8",
  "type": "vault_credential",
  "vault_id": "vault_019e3bb940277f0db05ab74291acf6ef",
  "auth": {
    "type": "mcp_oauth",
    "mcp_server_url": "https://mcp.example.com/mcp",
    "expires_at": "2026-08-16T08:00:00Z",
    "refresh": {
      "client_id": "oauth-client-id",
      "token_endpoint": "https://auth.example.com/oauth/token",
      "token_endpoint_auth": {"type": "client_secret_basic"},
      "resource": "https://mcp.example.com/mcp",
      "scope": "mcp.read mcp.write"
    }
  },
  "display_name": null,
  "metadata": {"team":"docs"},
  "archived_at": null,
  "created_at": "2026-05-18T15:34:35.387093Z",
  "updated_at": "2026-05-18T15:34:35.387093Z"
}

响应字段

字段	类型	说明
`id`	string	凭证唯一标识符（`vcred_` 前缀）
`type`	string	固定为 `"vault_credential"`
`vault_id`	string	所属 Vault 的 ID
`auth`	object	脱敏后的鉴权信息；不会返回密文
`display_name`	null	当前固定为 `null`
`metadata`	object	与 credential 一起存储的自定义元数据对象；省略时为 `{}`
`archived_at`	string \| null	归档时间；active 时为 `null`
`created_at`	string	创建时间（ISO 8601）
`updated_at`	string	最后更新时间（ISO 8601）

错误码

HTTP	type	触发条件
400	`invalid_request_error`	缺少 `auth`、凭证类型非法、缺少必需 auth 字段或 `metadata` 非法
401	`authentication_error`	缺少或无效的认证令牌
404	`not_found_error`	Vault 不存在或无权访问
409	`conflict_error`	Vault 已归档、active 凭证数已达上限，或该 MCP server 已存在 active 凭证

注意事项

响应中不会返回 token、access_token、refresh_token、client_secret 等密文
protocol 不是 nested auth 请求字段；Credential 通过 mcp_server_url 匹配
一个 Vault 最多可以包含 20 个 active 凭证
凭证创建后立即为 active 状态

完整错误信封说明详见错误参考。

Vaults

安全地存储凭据并注入到 Agent Session。

​请求头

​路径参数

​请求体

​请求示例

​Static Bearer

​导入 MCP OAuth token

​示例响应

​响应字段

​错误码

​注意事项

​相关

Vaults

请求头

路径参数

请求体

请求示例

Static Bearer

导入 MCP OAuth token

示例响应

响应字段

错误码

注意事项

相关