Skip to main content
Vaults

校验 MCP OAuth 凭证

实时检查 mcp_oauth Credential 能否通过其 MCP Server 的认证。

POST /api/v1/cloud/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate 对 active 状态的 mcp_oauth Credential 做实时校验:若 Credential 持有 refresh token,CAS 先尝试刷新(刷新成功会持久化轮换后的 token),然后用当前 access token 向 MCP Server 发起 initialize 探测。

路径参数

参数类型说明
vault_idstringVault ID,vault_ 前缀
credential_idstringCredential ID,vcred_ 前缀;必须是 active 的 mcp_oauth Credential

请求头

Header必填说明
AuthorizationBearer <PAT 或 SAT>
Content-Typeapplication/json

请求体

发送空 JSON 对象:
{}

示例请求

curl -X POST "https://api.qoder.com/api/v1/cloud/vaults/vault_019e3bb940277f0db05ab74291acf6ef/credentials/vcred_019e3bb98877759e862750b495c1fce8/mcp_oauth_validate" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{}'

示例响应

HTTP 200 OK
{
  "credential_id": "vcred_019e3bb98877759e862750b495c1fce8",
  "vault_id": "vault_019e3bb940277f0db05ab74291acf6ef",
  "type": "vault_credential_validation",
  "status": "invalid",
  "validated_at": "2026-08-19T02:58:16Z",
  "has_refresh_token": false,
  "refresh": {
    "status": "no_refresh_token",
    "http_response": null
  },
  "mcp_probe": {
    "method": "initialize",
    "http_response": {
      "status_code": 401,
      "content_type": "application/json",
      "body": "{\"error\":\"invalid_token\"}",
      "body_truncated": false
    }
  }
}

响应字段

字段类型说明
credential_id / vault_idstring被校验的 Credential 及其所属 Vault
typestring固定为 vault_credential_validation
statusstring总体结论:validinvalidunknown
validated_atstring校验时间,RFC 3339 格式
has_refresh_tokenbooleanCredential 是否存有 refresh token
refresh.statusstringno_refresh_tokensucceededfailedconnect_error
refresh.http_responseobject | null刷新失败时捕获的 token endpoint 响应
mcp_probeobject | null仅 MCP 探测失败时出现;method 为失败的 MCP 调用名
*.http_responseobjectstatus_codecontent_typebody(有长度上限且已脱敏)、body_truncated

状态语义

  • valid — MCP Server 接受了携带当前 access token 的 initialize 探测。
  • invalid — 确定性拒绝:探测或刷新收到 4xx 响应(408/429 除外),或 Credential 没有可用的 access token。
  • unknown — 无法得出结论:连接错误、超时、408/429 或 5xx。请稍后重试,不要直接判定凭证失效。
刷新 succeeded 时会顺带更新存储的 token,因此校验可以"治愈"临近过期的 Credential。

错误

HTTP类型触发条件
404not_found_errorVault 或 Credential 不存在或不可访问
409conflict_errorCredential 已归档,或类型不是 mcp_oauth