Collections Authentication

Overview

BT Collections authenticates API callers with a Bearer token issued inside the Collections product. This is not the Billtrust Platform authentication flow (X-Billtrust-Api-Key / X-Billtrust-Auth on arc-aegis.billtrust.com).

	Platform APIs (Credit, Dispute, User, …)	Collections API
Host	arc-aegis.billtrust.com (or ext proxy)	https://{your-collections-platform-host}
Credential	API Key or access token	Collections API token
Header	X-Billtrust-Api-Key or X-Billtrust-Auth	Authorization: Bearer <token>
Where created	Platform Authentication / user profile	Collections Settings → API Tokens

Create a token

1. Sign in to your BT Collections platform as an administrator.
2. Open Settings → API Tokens (Exports / API area).
3. Create a token and grant the scopes your integration needs.
4. Store the token securely when it is shown. You will not be able to retrieve the raw token value again later.

For the endpoints in this external documentation, grant at least:

• Read on scope collection for list/get endpoints
• Write on scope collection for POST /debtor-custom-fields-bulk-update and PATCH /external-workspace-items

Optional IP allowlisting can be configured per token in the same settings screen.

Use the token

Pass the token on every authenticated request:

curl -X GET 'https://{your-collections-platform-host}/api/v1/companies' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer <token>'

Example success

HTTP 200 with a JSON batch body (see Batching and filters).

Common errors

HTTP	Meaning
401	Missing/invalid token
403	Token lacks required scope, company access, or IP not allowlisted
404	Unknown path or entity
4xx/5xx	See JSON status, code, and message in the error body

Error body shape:

{
  "status": "403",
  "code": "INVALID_SCOPE",
  "message": "Invalid scope for token, scope 'collection' is required"
}

Public endpoints

These meta endpoints do not require a token:

• GET /version
• GET /is-active

Swagger UI authorize

In Swagger UI, use Authorize and enter your Bearer token. Also set the platform-host server variable to your Collections hostname.