Gateway Overview
Every partner API call enters through the integration gateway. The gateway decides whether the route exists, whether it needs a token, and whether your token carries the permission the route requires; only then does it forward the call to the integration service, which applies your client's own checks (certificate, IP allow-list, rate and usage limits) and runs the operation.
┌────────┐ TLS (+ client cert) ┌──────┐ ┌─────────┐ ┌─────────────┐
│ Client │ ──────────────────────▶ │ Edge │ ──▶ │ Gateway │ ──▶ │ Integration │
└────────┘ └──────┘ └─────────┘ └─────────────┘
What the gateway checks
| Step | Check | Refusal |
|---|---|---|
| 1 | The method and path are on the gateway's route allow-list | 404 |
| 2 | For a protected route: an Authorization: Bearer <access_token> header with a token signed by the platform | 401 |
| 3 | The token carries every permission the route requires (each endpoint page lists it as Required permission) | 403 |
| 4 | The token is still your client's live access token | 401 |
Then the integration service checks, in order: the token again, your client certificate when the client requires one, your IP allow-list, the rate limit and the monthly usage limit. See Errors for the bodies these refusals carry.
The allow-list is deny-by-default. A route that is not listed answers 404 at the gateway even if the service implements it. Every route in this documentation is on the allow-list.
Permissions
A token issued with the client_credentials grant carries the scopes configured on your client; one issued with the password grant carries the supervisor's role permissions (see Create a Token). Ask the operator to add a scope when an endpoint answers 403.
Every protected route requires at least one permission. A few admin routes are additionally restricted to the platform owner's node by the service itself; their pages say so.
Public routes
These routes need no Authorization header:
| Route | Purpose |
|---|---|
GET /health, GET /v1/health, GET /v2/health | Liveness probes |
POST /v2/oauth/token | Issues tokens. See Create a Token |
POST /v2/webhooks/custodial | Inbound custody webhooks, authenticated by the provider's own secret. See Receive Custodial Webhook |
POST /v2/webhooks | Deprecated alias of the route above |
/v2/mcp, /v2/mcp/** | Model Context Protocol transport for MCP-enabled clients, authenticated by the integration service with the client secret as bearer token |
Request headers
| Header | Required | Description |
|---|---|---|
Authorization | Protected routes | Bearer <access_token> |
Content-Type | Requests with a body | application/json, or multipart/form-data where the endpoint takes files |
X-Correlation-ID | No | Your trace id for the call. The gateway generates one when absent and forwards it to the service, so quote it when you report an issue |
Audit
The gateway records every call (method, path, status, timing, correlation id and the request/response bodies) for the platform's audit trail.