Referral Partner Authentication

Referral Partners use two-layer authentication:

1. API Key — Authenticates with the Referral Partner API
2. JWT Bearer Token — Authenticates with the Customer API when acting on behalf of referred clients

See How It Works for why two APIs exist and when to use each.

Layer 1: Referral Partner API

Include your API key in the XApiKey header for all Referral Partner API requests:

GET /clients HTTP/1.1
Host: referral-api.debitura.com
XApiKey: YOUR_API_KEY

Contact partnerships@debitura.com to obtain your API key.

For base URLs (including test environment), see Environments.

Layer 2: Customer API (JWT Tokens)

To submit cases on behalf of referred clients, generate a JWT token using the OAuth endpoint:

POST /oauth/token HTTP/1.1
Host: referral-api.debitura.com
XApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "externalTenantId": "your-tenant-identifier"
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 1800,
  "externalTenantId": "your-tenant-identifier",
  "creditorId": "uuid-of-linked-creditor"
}

Token Details

Property	Value
Algorithm	HS256
Expiry	30 minutes (1800 seconds)
Refresh	Not supported — request a new token when expired

Using the Token

Include the JWT in Customer API requests via the Authorization header:

POST /cases HTTP/1.1
Host: customer-api.debitura.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "debtor": { ... },
  "claims": [ ... ]
}

Token Expiry Handling

Tokens expire after 30 minutes. Unlike typical OAuth flows, there is no refresh token — you must mint a new token when the current one expires.

:::warning This is different from most OAuth implementations Most OAuth providers issue a refresh token alongside the access token. Debitura does not. Plan your implementation to handle token expiry by re-minting. :::

Recommended pattern: wrap Customer API calls in a retry-on-401 handler:

async function callCustomerApi(method, path, body, externalTenantId) {
  let token = await getOrMintToken(externalTenantId);

  let response = await fetch(`https://customer-api.debitura.com${path}`, {
    method,
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: body ? JSON.stringify(body) : undefined,
  });

  // Token expired — mint a new one and retry once
  if (response.status === 401) {
    token = await mintNewToken(externalTenantId);
    response = await fetch(`https://customer-api.debitura.com${path}`, {
      method,
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: body ? JSON.stringify(body) : undefined,
    });
  }

  return response;
}

Key points:

• Cache tokens per externalTenantId and reuse them until they expire
• On 401 Unauthorized, mint a fresh token and retry the request once
• Do not retry more than once — a second 401 means the client link is invalid, not just an expired token

For rate limits, see Rate Limiting. For full endpoint details, see the Referral Partner API Reference and Customer API Reference.