Authentication - Debbie Creditor API Documentation

Authentication with an API key can be done by using a bearer token in the Authorization header. This is done using the following format Authorization: Bearer {token}.

Authorization: Bearer {token}

API keys are issued and revoked directly from the creditor portal. Go to the Developer section in the menu, click API, name the API key and select the scopes it needs. The key is only shown once, when it is created. On the same page you will find the tenantId and creditorId used in the API calls.

Creditor id

Include creditorId as a query parameter on every request, including requests that already identify a customer, file, webhook or billing in the URL. Use the creditor id shown alongside your API key in the creditor portal.

GET /v1/{tenantId}/customers/{customerId}?creditorId={creditorId}
Authorization: Bearer {token}

POST /v1/{tenantId}/customers/{customerId}/add-case-vouchers?creditorId={creditorId}
Authorization: Bearer {token}
Content-Type: application/json

Use the same creditorId as when creating the customer. The customer id does not replace it, and a creditorId in the request body does not replace the query parameter. If the query parameter is missing or does not match a creditor the API key can access, the API returns 401 Unauthorized with the message You do not have access to the requested creditor.

Scopes

Every endpoint requires a scope, and a key only reaches the endpoints its scopes cover. A scope is an access level and an area joined by a colon:

read:customers
write:case-vouchers

The access level follows the HTTP method — GET requires read, and every other method requires write. The area is named on each endpoint under Required scope. Grant a key the narrowest set that covers what it does.

Scopes available to a creditor key

A key issued from the creditor portal can hold these scopes, and no others:

Area	Scopes
Customers	`read:customers`, `write:customers`
Cases	`read:cases`, `write:cases`
Case vouchers	`read:case-vouchers`, `write:case-vouchers`
Voucher types	`read:voucher-types`
Ultimate creditors	`read:ultimate-creditors`
Files	`write:files`
Documents	`write:documents`
Billings	`read:billings`
Interactions	`write:interactions.create`
Webhooks	`read:webhooks`, `write:webhooks`
Insights	`read:insights.cases`, `read:insights.case-vouchers` and the other insight areas

Registering a direct payment is a case voucher write, so it needs write:case-vouchers rather than a scope of its own. A key is always bound to one creditor, and the endpoints in this reference only ever reach that creditor’s data — its customers, its cases and its settlements.

Sub-areas

Some areas have a sub-area, written with a dot:

write:interactions.create

A scope grants exactly what it names. write:interactions does not grant write:interactions.create, and write:interactions.create does not grant write:interactions. If a key needs both, give it both.

When a scope is missing

A request made with a key that lacks the required scope is rejected with 401 Unauthorized:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "You do not have permission to access this resource",
  "requestId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}

The scopes on an existing key can be changed under Developers → API in the creditor portal without reissuing it.

​Creditor id

​Scopes

​Scopes available to a creditor key

​Sub-areas

​When a scope is missing

Creditor id

Scopes

Scopes available to a creditor key

Sub-areas

When a scope is missing