Authentication and first request

Before you begin

You need a partner account. If you do not have one, request access.

1. Create client credentials.
   Open Developer settings in the partner portal and select the environment you want credentials for.
2. Store the client secret.
   The secret is shown once when created or rotated. Store it in a secret manager.
3. Request an access token.
   Use the client credentials grant with the channel partner server scope.

1. Request an access token

Send this request from your server or a local API client. Do not include client credentials in application source code.

curl --request POST 'token URL' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'scope=channel-partner-api/server'

2. Send an API request

Add the returned access token to the Authorization header as a bearer token. The selected API base URL is loading.

curl 'API URL/v1/channel-partners/me' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

3. Handle API errors

Every client API HTTP error uses code, message and fields by default. No opt-in is needed. Branch on the code or HTTP status and show the message to the user.

{
  "code": "VALIDATION_ERROR",
  "message": "One or more request fields are invalid.",
  "fields": [{
    "location": "body",
    "path": "/amount",
    "code": "INVALID_TYPE",
    "message": "Amount must be an integer in cents."
  }]
}

Body paths use JSON Pointer, for example /individuals/1/externalId. An empty path means the whole body. Other locations are query, path and header. Non-field errors return fields: [].

Optional details contains documented context such as evidence availability or public verification branding. Always provide a fallback for unknown codes and non-JSON network failures. HTTP statuses and successful responses keep their existing meaning. Provider webhook acknowledgements and OAuth token errors follow their own protocols.

Migration: replace reads of the former error property or machine codes in message with code. Error metadata such as reason, fetchedAt and partnerId moves under details. Strict clients require an update before cutover.

4. Where to go next

The guides show how the endpoints fit together for a whole workflow. The reference lists every endpoint with its request bodies, response schemas and errors.