应用凭证与授权

调用方通过「应用凭证」访问受保护的 API。一个凭证包含 AppKey 与 AppSecret，可以设置为项目级通行证，也可以逐接口授权。

入口

登录后进入 账户中心 → 应用凭证。列表按当前项目隔离，只展示本项目创建的凭证。

凭证列表

列	说明
ID	凭证 ID
名称	应用名称，点击可查看详情
AppKey	调用时使用的应用标识
作用域	接口级（`api`）或项目级（`project`）
IP 限制	是否配置了 IP 白名单
创建人	凭证创建者
最后修改	最近更新时间
操作	MCP 配置、授权列表、编辑、删除

凭证的启用/禁用能力保留在后端接口中，当前列表未开放切换入口。

操作说明

MCP 配置：仅当凭证启用了 MCP 时可用，弹窗给出可直接复制的 MCP 客户端 JSON；
授权列表：查看并取消该凭证已获得的接口授权；
编辑：修改名称、AppKey、AppSecret、作用域、IP 白名单、MCP 开关和备注；
删除：删除凭证会同时移除其授权关系，已使用该凭证的调用将立即失败。

新建凭证

字段	必填	说明
名称	是	应用名称，最长 25 个字符，输入时会自动去除空格
AppCode	是	应用编码，创建后不可修改；规则为 `^[a-zA-Z][a-zA-Z0-9]{4,24}$`，即字母开头、5–25 位字母或数字
AppKey	是	默认生成 `ak_` 加 32 位随机串，可手动修改或重新生成
AppSecret	是	默认生成 32 位随机串，可手动修改或重新生成
作用域	是	`api` 或 `project`，见下文
IP 白名单	否	多个 IP 用英文逗号分隔，也支持 `起始IP~结束IP` 区间
启用 MCP	否	勾选后该凭证可通过 `/mcp/{appCode}` 访问 MCP 服务
备注	否	用途说明

AppCode 在输入框失焦时会检查是否重复；即使重复只提示警告，保存时仍会由后端做唯一性校验。修改凭证时 AppCode 不可编辑。

妥善保管 AppSecret

AppSecret 只在创建/编辑时可见，请通过安全渠道交付调用方。泄露后应立即在编辑弹窗中重新生成，并同步更新调用方配置。

作用域

作用域	授权范围	调用校验
接口级 `api`	仅被授权列表中的接口	校验接口授权、接口认证方式、IP 白名单
项目级 `project`	当前项目内所有已上线接口	项目内直接放行，不再校验接口级授权、接口认证方式和 IP 白名单

项目级凭证相当于项目内通行证，适合内部服务间调用。它绕过接口自身的签名校验，因此必须严格控制发放范围；面向外部合作方时应使用接口级凭证。

MCP 的差异

通过 /mcp/{appCode} 调用时，无论作用域是 api 还是 project，网关都会校验凭证的 IP 白名单、mcpEnabled 开关和路径中的 AppCode。接口级凭证只暴露已授权的 MCP 接口，项目级凭证暴露项目内全部已发布为 MCP 的生产接口。

接口授权

接口授权的来源有三种：

调用方在接口详情页提交订阅申请，审批通过后自动授权；
接口负责人在 接口列表 → 授权 中直接授权；
项目级凭证无需逐接口授权。

在凭证的「授权列表」中可以查看授权接口编码、接口名称、授权时间和授权人，并点击「取消授权」移除某条授权。取消后该凭证对该接口的调用立即被拒绝。

IP 白名单

IP 白名单用于收敛调用来源：

多个条目用英文逗号分隔，例如 10.0.0.1,10.0.0.2；
支持区间写法 10.0.0.1~10.0.0.100；
前端表单按 IPv4 校验，后端同时支持 CIDR 网段；
接口级凭证在 REST 调用和 MCP 调用时都会校验来源 IP；
项目级凭证在 REST 调用时不校验 IP，在 MCP 入口仍会校验。

来源 IP 不在白名单时返回 HTTP 200，业务码 40018。

MCP 配置

凭证启用 MCP 后，点击「MCP 配置」可以看到客户端配置：

{
  "mcpServers": {
    "ApiGo-MCP": {
      "type": "http",
      "url": "https://www.apigo.cn/mcp/{appCode}",
      "headers": {
        "X-AppKey": "{AppKey}"
      }
    }
  }
}

url 中的 {appCode} 会自动替换为当前凭证的 AppCode；
headers 中的占位符需要替换为实际 AppKey；
该弹窗展示的是 SaaS 站点默认地址，私有化部署时应替换为实际网关域名；
MCP 调用只需要 X-AppKey，不需要 X-Sign；也可改用 OAuth2 token（Authorization: Bearer <access_token>），见下文。

协议细节和工具暴露规则见 MCP 接入。

OAuth2 接入

同一份凭证也可以作为 OAuth2 客户端凭证使用（接口认证方式选择「OAuth2 客户端凭证」）：

client_id = 凭证的 AppKey，client_secret = AppSecret，无需额外创建密钥；
token 端点为与网关同源的 POST /oauth2/token，grant_type=client_credentials，默认有效期 30 分钟；
调用接口或 MCP 时携带 Authorization: Bearer <access_token>，无需计算签名；
凭证编辑弹窗中的「OAuth2 接入」一行展示了 token 端点，便于复制交付给调用方；
凭证被禁用或删除后 token 立即失效；轮换 AppSecret 后需重新换取 token。

适用情形：调用方是标准 OAuth2 客户端、Agent 或后端服务，不便实现 SM3 签名算法时。面向外部合作方仍应使用接口级凭证，并配置 IP 白名单收敛来源。

完整的换取流程、错误码与多语言示例见 OAuth2 客户端凭证认证。

企业 IdP JWT 接入

当企业已统一使用 Keycloak、Azure AD 等 IdP 时，可以让平台直接校验 IdP 签发的 JWT，而不再由平台签发 token：

凭证需要绑定 (jwt_idp, jwt_subject)，网关据此把 JWT 主体映射到应用；
绑定入口在凭证编辑弹窗的「JWT 身份绑定」，IdP 与主体必须同时填写或同时清空；
同一项目内同一主体只能绑定一个应用；
调用方携带 Authorization: Bearer <enterprise_token>，不需要 AppKey、AppSecret 或签名；
认证失败返回 HTTP 401/403/503 + WWW-Authenticate，与平台 OAuth2 的 HTTP 200 契约不同；
JWT 暂不支持 MCP 入口，二期开放。

配置方法、claims 要求与完整调用流程见 JWT 企业 IdP 认证。

凭证与订阅的关系

接口级凭证：先获得接口授权（订阅审批或负责人授权），再受订阅的日调用量与有效期约束；
项目级凭证：不需要逐接口订阅，直接访问项目内接口，但仍受接口治理规则（流控、熔断、IP 规则、WAF 等）约束；
凭证被删除或停用后，相关订阅和 MCP 访问同时失效。

安全建议

不同调用方使用不同凭证，避免共用；
优先使用接口级凭证，确有必要时再使用项目级凭证；
为生产调用配置 IP 白名单；
定期轮换 AppSecret，轮换后及时通知调用方；
不要在代码仓库、前端代码或日志中明文保存 AppSecret。

入口​

凭证列表​

操作说明​

新建凭证​

作用域​

接口授权​

IP 白名单​

MCP 配置​

OAuth2 接入​

企业 IdP JWT 接入​

凭证与订阅的关系​

安全建议​

相关文档​

入口