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

# Customize Agent Portal

> Render a user account, payment methods, orders, refunds, and authorizations in an Agent Platform portal.

An Agent Platform can use Clink as the account and payment data source behind its own portal. The platform backend authenticates as itself, obtains a read-only token for one user, and calls Clink REST APIs to render that user's data.

The portal API never performs a write. It does not create orders, issue refunds, change payment methods, or modify purchase authorizations.

## How it works

```mermaid theme={null}
sequenceDiagram
  participant P as Platform backend
  participant C as Clink cwallet
  participant U as Platform web
  P->>C: client_credentials (platform client)
  C-->>P: Platform client token
  P->>C: POST /agent/cwallet/platform/portal/tokens {email}
  C-->>P: Portal user token (aud=clink-agent-platform-portal, scope=portal:read)
  P->>C: GET /agent/platform/** with portal token
  C-->>P: User-scoped account, orders, refunds, authorizations
  P-->>U: Render the user's Clink data
```

The platform client is the same pre-registered client used by [Agent Platform MCP Login](https://docs.clinkbill.com/api-reference/mcp/agent_platform_login.md). The portal token is a separate user token and is valid only for the portal read APIs.

## What you can build

| Area | Clink data |
| - | - |
| Account | Customer ID, email, name, country, and wallet readiness. |
| Payment methods | Card and wallet display metadata; never PAN or CVV. |
| Orders | The user's order history, including orders created by any Agent. |
| Refunds | Refund list and details. |
| Authorizations | Purchase instructions, mandates, limits, validity, and usage records. |

## Token types

| Token | Used for | Audience / scope |
| - | - | - |
| Platform client token | Calling `/platform/sessions`, `/platform/portal/tokens`, and other platform server APIs. | `clink-agent-platform-api` / `agent-platform:account` |
| Portal user token | Calling the read-only `/agent/platform/**` APIs for one user. | `clink-agent-platform-portal` / `portal:read` |
| MCP user token | Calling the user's MCP endpoint and tools. | Environment MCP resource / MCP scopes |

The portal user token cannot call `/mcp`, and the MCP token cannot call `/agent/platform/**`. Keep the platform token on the server; do not send it to the platform's browser or to an Agent.

## Data scope

The portal token's `sub` is the Clink `customer_id`. Clink resolves the user only from that verified token; there is no request parameter for choosing a different `customer_id` or email.

Portal data is scoped to the user, not to an Agent:

* Orders, refunds, and authorizations include data created by any Agent for that user.
* The response does not filter by `agent_client_id` or `agentInfo.clientId`.
* A customer cannot read another customer's records; single-record endpoints return `404` when the record is not owned by the token's user.
* Order filtering uses a bounded scan. The order list response includes `truncated` when the scan limit was reached.

## Prerequisites

Clink must pre-register the platform client in the target environment with:

* A platform `client_id` and `client_secret`.
* The exact OAuth `redirect_uri` used for first-time user authorization.
* The environment MCP resource and the MCP scopes.
* The portal audience and `portal:read` scope.

The platform must verify the user's email before requesting a token. The platform client cannot be created through Dynamic Client Registration.

## Environment endpoints

| Environment | 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 surface

| Method | Path | Auth |
| - | - | - |
| `POST` | `/agent/cwallet/platform/portal/tokens` | Platform client token |
| `GET` | `/agent/platform/me` | Portal user token |
| `GET` | `/agent/platform/payment-methods` | Portal user token |
| `GET` | `/agent/platform/orders` | Portal user token |
| `GET` | `/agent/platform/orders/{orderId}` | Portal user token |
| `GET` | `/agent/platform/refunds` | Portal user token |
| `GET` | `/agent/platform/refunds/{refundOrderId}` | Portal user token |
| `GET` | `/agent/platform/authorizations` | Portal user token |
| `GET` | `/agent/platform/authorizations/{instructionId}` | Portal user token |

> [card] [Portal token](https://docs.clinkbill.com/api-reference/agent-portal/portal_token.md)
>
> Exchange the platform client token for a read-only token for one user.

> [card] [Read APIs](https://docs.clinkbill.com/api-reference/agent-portal/read_apis.md)
>
> Account, payment methods, orders, refunds, and authorizations.


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