OAuth

Base URL: https://referral-api.debitura.com
Authentication: API key in the XApiKey header

Get OAuth access token

POST/oauth/token

Generates a short-lived JWT bearer token for accessing the Customer API on behalf of a specific client.

How It Works:

Authenticate with your referral partner API key (XApiKey header)
Provide the externalTenantId of the client you want to access
Receive a Bearer token valid for 30 minutes
Use the token in the Customer API: Authorization: Bearer {access_token}

Requirements:

The externalTenantId must match an active ReferralPartnerClientLink for your partner account
SDCA completion is not required to mint a token; contract requirements are enforced when submitting a case

Token Details:

Type: Bearer (JWT)
Lifetime: 30 minutes
Scope: Customer API access for the specified client only

Usage Example:

POST /oauth/token
{ "externalTenantId": "your-client-id" }

Response:
{ "accessToken": "eyJ...", "tokenType": "Bearer", "expiresIn": 1800 }

Request body

externalTenantIdstringRequired
The partner's external identifier for the client/tenant. This must match an active ReferralPartnerClientLink.
Max 255 characters

Returns

200 Token generated successfully

accessTokenstringnullable
The JWT bearer token to use in Authorization header. Format: "Bearer {access_token}"
expiresIninteger
Token lifetime in seconds (typically 1800 for 30 minutes).
creditorIduuid
The Debitura creditor ID that this token grants access to.
externalTenantIdstringnullable
The partner's external tenant ID for reference.
tokenTypestringnullable
Token type - always "Bearer" for JWT tokens.

Errors

`400`	Invalid request (missing or invalid externalTenantId)
`404`	Client not found (no active client link found for externalTenantId)
`500`	Internal server error

Every error uses the same body shape. See Error handling.

POST/oauth/token

curl -X POST https://referral-api.debitura.com/oauth/token \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalTenantId": "string"
  }'

Response

{
  "accessToken": "string",
  "expiresIn": 3,
  "creditorId": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "externalTenantId": "string",
  "tokenType": "string"
}