> ## 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.

# 定制 Agent Portal

> 在 Agent Platform 的 Portal 中展示用户的 Clink 账户、支付方式、订单、退款和授权数据。

Agent Platform 可以把 Clink 作为自己 Portal 背后的账户和支付数据源。平台后端先以自身身份认证，再为单个用户获取只读 token，通过 Clink REST API 展示该用户的数据。

Portal API **不提供任何写操作**：不创建订单、不发起退款、不修改支付方式，也不修改购买授权。

## 工作方式

```mermaid theme={null}
sequenceDiagram
  participant P as 平台后端
  participant C as Clink cwallet
  participant U as 平台 Web
  P->>C: client_credentials（平台 client）
  C-->>P: 平台 client token
  P->>C: POST /agent/cwallet/platform/portal/tokens {email}
  C-->>P: Portal 用户 token（aud=clink-agent-platform-portal，scope=portal:read）
  P->>C: 使用 portal token 调 GET /agent/platform/**
  C-->>P: 该用户的账户、订单、退款、授权数据
  P-->>U: 渲染用户的 Clink 数据
```

平台 client 与 [Agent Platform MCP 登录](https://docs.clinkbill.com/cn/api-reference/mcp/agent_platform_login.md) 使用的是同一个预注册 client。Portal token 是独立的用户 token，只能用于 Portal 只读 API。

## 可以构建的内容

| 模块 | Clink 数据 |
| - | - |
| 账户 | customer ID、邮箱、姓名、国家、钱包状态。 |
| 支付方式 | 卡和钱包的展示信息；不返回 PAN/CVV。 |
| 订单 | 用户订单历史，包括任意 Agent 创建的订单。 |
| 退款 | 退款列表与详情。 |
| 授权 | 购买指令、mandate、额度、有效期和使用记录。 |

## Token 类型

| Token | 用途 | Audience / scope |
| - | - | - |
| 平台 client token | 调 `/platform/sessions`、`/platform/portal/tokens` 等平台服务端接口。 | `clink-agent-platform-api` / `agent-platform:account` |
| Portal 用户 token | 调 `/agent/platform/**` 只读接口，代表一个用户。 | `clink-agent-platform-portal` / `portal:read` |
| MCP 用户 token | 调用户 MCP endpoint 和 MCP 工具。 | 环境 MCP resource / MCP scopes |

Portal 用户 token 不能调 `/mcp`，MCP token 也不能调 `/agent/platform/**`。平台 client token 只保存在服务端，不要发给平台浏览器或 Agent。

## 数据范围

Portal token 的 `sub` 是 Clink `customer_id`。Clink 只从这个经过验证的 token 解析用户；没有通过请求参数指定其他 `customer_id` 或邮箱的入口。

Portal 数据按用户隔离，而不是按 Agent 过滤：

* 订单、退款和授权包含该用户下任意 Agent 创建的数据；
* 响应不按 `agent_client_id` 或 `agentInfo.clientId` 过滤；
* 用户不能读取其他用户的记录；单条记录不属于当前用户时返回 `404`；
* 订单过滤使用有界扫描；达到扫描上限时订单列表返回 `truncated`。

## 前置条件

Clink 需要在目标环境预注册平台 client：

* 平台 `client_id` 和 `client_secret`；
* 首次用户授权使用的精确 OAuth `redirect_uri`；
* 环境 MCP resource 和 MCP scopes；
* Portal audience 和 `portal:read` scope。

平台必须先验证用户邮箱，再请求 token。平台 client 不能通过 Dynamic Client Registration 自行创建。

## 环境地址

| 环境 | API Base URL | MCP resource |
| - | - | - |
| Sandbox UAT | `https://uat-api.clinkbill.com` | `https://uat-api.clinkbill.com/mcp` |
| Production | `https://api.clinkbill.com` | `https://api.clinkbill.com/mcp` |

## API 列表

| Method | Path | 认证 |
| - | - | - |
| `POST` | `/agent/cwallet/platform/portal/tokens` | 平台 client token |
| `GET` | `/agent/platform/me` | Portal 用户 token |
| `GET` | `/agent/platform/payment-methods` | Portal 用户 token |
| `GET` | `/agent/platform/orders` | Portal 用户 token |
| `GET` | `/agent/platform/orders/{orderId}` | Portal 用户 token |
| `GET` | `/agent/platform/refunds` | Portal 用户 token |
| `GET` | `/agent/platform/refunds/{refundOrderId}` | Portal 用户 token |
| `GET` | `/agent/platform/authorizations` | Portal 用户 token |
| `GET` | `/agent/platform/authorizations/{instructionId}` | Portal 用户 token |

> [card] [Portal token](https://docs.clinkbill.com/cn/api-reference/agent-portal/portal_token.md)
>
> 用平台 client token 换取一个用户的只读 token。

> [card] [只读接口](https://docs.clinkbill.com/cn/api-reference/agent-portal/read_apis.md)
>
> 账户、支付方式、订单、退款和授权。


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