> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何获取平台凭据

> 向 Clink 申请 client_id 和 client_secret，并了解 Pre-registration、CIMD 和 DCR 三种注册方式分别适用于哪种接入。

MCP、RESTful API 和 Vault SDK 三种接入方式都要先向 Clink 取得 `client_id`；平台服务端要调用 Clink 接口时，还需要 `client_secret`。本页说明怎么申请、Clink 会登记什么，以及三种注册方式分别适用于哪种接入。取得凭据后，回到对应的接入文档继续：[如何对接 MCP](https://docs.clinkbill.com/cn/guides/agent/platform_integration/mcp_integration.md)、[如何对接 RESTful API](https://docs.clinkbill.com/cn/guides/agent/platform_integration/restful_api.md)或[如何对接 Vault SDK](https://docs.clinkbill.com/cn/guides/agent/platform_integration/vault_sdk.md)。

## 选择注册方式

| 注册方式 | 得到什么 | 适用的接入方式 |
| - | - | - |
| **Pre-registration**（推荐） | Clink 签发的 `client_id` 和 `client_secret` | MCP、RESTful API、Vault SDK |
| **CIMD** | 公开的 `client_id`（元数据文件的 URL），没有 `client_secret` | 仅 MCP |
| **DCR** | 动态注册得到的 `client_id`，没有 `client_secret` | 仅 MCP |

平台服务端调用 `/platform/sessions`、Portal API 或 Vault 时必须用 `client_secret` 换取平台 Token，所以 RESTful API 和 Vault SDK 只能使用 Pre-registration，平台 client 也不能通过 DCR 自行创建。CIMD 和 DCR 只适合自己开发 MCP Host、让每位用户直接完成标准 OAuth 授权的场景。

## Pre-registration（推荐）

由 Clink 在目标环境为你登记 client 并签发凭据。Clink 为每个环境分别签发：Sandbox UAT（`https://uat-api.clinkbill.com`）和 Production（`https://api.clinkbill.com`）的凭据不能混用。

### 向 Clink 提供

* 应用名称、技术联系人和目标商户场景。
* Sandbox UAT 和 Production 的部署信息。
* 首次用户授权使用的固定 HTTPS `redirect_uri`。MCP 和 RESTful API 需要；Vault SDK 不需要。
* 要使用的接入方式和能力，Clink 据此登记 Scope，见下表。
* 推荐：平台 RSA 公钥，见[登记 RSA 公钥](#rsa-public-key)。

### Clink 签发

| 接入方式 | 凭据 | 登记的 Scope |
| - | - | - |
| MCP | 平台 `client_id` 和 `client_secret` | 平台 Scope `agent-platform:account`，以及按平台能力统一配置的用户 Token MCP Scope，见[Scope 配置](https://docs.clinkbill.com/cn/guides/agent/platform_integration/mcp_integration.md#scopes) |
| RESTful API | 与 MCP 共用同一个平台 client | 平台 Scope `agent-platform:account`，以及 Portal Scope `portal:read portal:write` |
| Vault SDK | 独立的 Vault `client_id` 和 `client_secret` | `vault:session vault:pay vault:read` |

同时接入 MCP 和 RESTful API 时只需要一个平台 client。Vault SDK 的凭据单独签发，不能和平台 client 混用。

自己开发 MCP Host、只需要 public client 时，也可以请 Clink 只登记 `client_id`、不签发 `client_secret`。这种 client 的授权方式与 CIMD、DCR 相同，见[发起用户授权](#public-client-authorization)。

### 登记 RSA 公钥

如果希望支付凭证以加密的 `key` / `payload` 返回，线下联系 Clink，为每个环境登记 PEM X.509 SubjectPublicKeyInfo 格式的 RSA 公钥（`BEGIN PUBLIC KEY`）。公钥登记和 client 登记是两个独立步骤。

* MCP 的 `get_credential` 和 RESTful API 的 `POST /agent/platform/credential` 都使用这把公钥；Vault SDK 不需要。
* RESTful API 未登记公钥且服务端没有开启明文模式时，凭证接口返回 `71211012`（`credential_public_key_not_configured`）。生产环境建议登记。
* 私钥只保存在平台可信组件中，解密方式见[加密凭证解密](https://docs.clinkbill.com/cn/guides/agent/browser_pay/decryption.md)。

### 保存凭据

你的后端需要保存：

* `CLINK_CLIENT_ID`、`CLINK_CLIENT_SECRET`。同时接入 Vault SDK 时，另存一组 Vault 凭据。
* 平台登记的精确 `redirect_uri`。
* RSA 私钥（如果登记了公钥）。

`client_secret` 和 RSA 私钥只能保存在可信服务端，不要放进浏览器代码、URL、日志、Agent 输入或普通业务消息。每个环境只使用一组平台凭据，所有用户共用；不要为每个用户或每次请求申请新的 client。

## CIMD

仅适用于 MCP。适合能在自己的 HTTPS 域名下托管公开 JSON 文件的 MCP Host。托管文件，并把文件 URL 作为 `client_id`：

```json theme={null}
{
  "client_id": "https://agent.example.com/.well-known/oauth-client.json",
  "client_name": "Example Agent",
  "redirect_uris": ["https://agent.example.com/oauth/clink/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "scope": "wallet:read wallet:setup payment:execute instruction:read instruction:write refund:read refund:write events:read events:consume offline_access"
}
```

Clink 会拉取这个文件来校验授权请求，文件需要满足：

* URL 使用 HTTPS，带路径，不带 query 和 fragment。
* 文件中的 `client_id` 与文件 URL 完全一致。
* 直接返回 HTTP 200，`Content-Type` 为 `application/json`；Clink 不会跟随跳转。
* 文件不超过 5 KB，不包含任何 Secret。

## DCR

仅适用于 MCP。适合不能托管公开 HTTPS 文件，或 Host 只支持动态注册的场景。先读取 `{API_BASE_URL}/.well-known/oauth-authorization-server`，只有返回 `registration_endpoint` 时才能使用 DCR：

```http theme={null}
POST {registration_endpoint}
Content-Type: application/json

{
  "client_name": "Example Agent",
  "redirect_uris": ["https://agent.example.com/oauth/clink/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "wallet:read wallet:setup payment:execute instruction:read instruction:write refund:read refund:write events:read events:consume offline_access"
}
```

持久化返回的 `client_id`。Clink 不支持修改已注册的 client：需要调整 redirect URI 或 Scope 时，重新注册一个 client，用户也要用新的 `client_id` 重新授权。

## CIMD 和 DCR 的共同规则

* 两者都是 public client，没有 `client_secret`，必须使用 Authorization Code + PKCE（S256）。
* 注册的 Scope 是之后每次授权请求的上限，超出会返回 `invalid_scope`，所以注册时要写全 Agent 可能用到的 Scope。
* 每个部署、租户或安装实例只注册一次，所有用户复用同一个 `client_id`。
* 没有 `client_secret` 就不能调用 `/platform/sessions`，取得 `client_id` 后需要自己发起用户授权，见下文。

### 发起用户授权

1. 读取 `{API_BASE_URL}/.well-known/oauth-protected-resource/mcp`，从 `authorization_servers` 取得 issuer。
2. 读取 `{issuer}/.well-known/oauth-authorization-server`，取得 `authorization_endpoint` 和 `token_endpoint`。不要把端点写死在代码里。
3. 为当前用户生成并临时保存 `state` 和 PKCE `code_verifier`，用 S256 计算 `code_challenge`。
4. 把用户重定向到 `authorization_endpoint`，参数全部 URL 编码：

```text theme={null}
response_type=code
client_id={CLIENT_ID}
redirect_uri=https://agent.example.com/oauth/clink/callback
scope=wallet:read payment:execute instruction:read instruction:write events:read events:consume offline_access
resource={MCP_URL}
state={RANDOM_STATE}
code_challenge={S256_CODE_CHALLENGE}
code_challenge_method=S256
```

回调校验和换取 Token 见 [Agent Platform MCP 登录](https://docs.clinkbill.com/cn/api-reference/mcp/agent_platform_login.md)，`client_id` 换成你取得的 public client 值。之后按[如何对接 MCP](https://docs.clinkbill.com/cn/guides/agent/platform_integration/mcp_integration.md)步骤 2 和步骤 3 配置 system prompt 和 MCP。遇到 `403 insufficient_scope` 时，从 `WWW-Authenticate` 响应头的 `scope` 参数读取所需 Scope，与已授予的 Scope 合并后让用户重新授权；合并结果不能超出注册的 Scope。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.