Authentication

The Alleviate API uses Microsoft Entra ID (formerly Azure AD) for authentication. You’ll need to obtain an OAuth 2.0 access token using the Client Credentials flow.

Prerequisites

Before you can authenticate, you’ll need:

1. Client ID (client_app_id) - Your application’s unique identifier
2. Client Secret (client_secret) - Your application’s secret key
3. Tenant ID (alleviate_tenant_id) - The Alleviate Azure AD tenant ID
4. Debt Core App ID (debt_core_app_id) - Used for the API scope

Tip

See the Environment Credentials section below for tenant and app IDs. Contact your account manager for client credentials.

Obtaining an Access Token

Use the OAuth 2.0 Client Credentials flow to obtain an access token:

cURL

curl -X POST "https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={CLIENT_ID}" \
  -d "client_secret={CLIENT_SECRET}" \
  -d "scope=api://{DEBT_CORE_APP_ID}/.default"

JavaScript

const axios = require('axios');

async function getAccessToken() {
  const TENANT_ID = 'your-tenant-id';
  const CLIENT_ID = 'your-client-id';
  const CLIENT_SECRET = 'your-client-secret';
  const DEBT_CORE_APP_ID = 'your-debt-core-app-id';

  const tokenUrl = `https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/token`;

  const params = new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    scope: `api://${DEBT_CORE_APP_ID}/.default`
  });

  const response = await axios.post(tokenUrl, params, {
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
  });

  return response.data.access_token;
}

Python

import requests

def get_access_token():
    TENANT_ID = 'your-tenant-id'
    CLIENT_ID = 'your-client-id'
    CLIENT_SECRET = 'your-client-secret'
    DEBT_CORE_APP_ID = 'your-debt-core-app-id'

    token_url = f"https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token"

    data = {
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "scope": f"api://{DEBT_CORE_APP_ID}/.default"
    }

    response = requests.post(token_url, data=data)
    return response.json()["access_token"]

Environment Credentials

Use the following values based on your target environment:

Variable	Sandbox	Production
alleviate_tenant_id	8797fa3f-ba90-4187-97fb-6ab892ea90355	8797fa3f-ba90-4187-97fb-6ab892ea9035
debt_core_app_id	aba793eb-f395-4f86-be59-7a7d0c1bfdb0	9060a1d0-da3b-4676-ad64-ff64465cce41
client_app_id	Provided by your account manager	Provided by your account manager
client_secret	Provided by your account manager	Provided by your account manager

Caution

Never commit or share your client secrets. Contact your account manager to obtain your client_app_id and client_secret.

Token Response

A successful authentication returns:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6..."
}

Field	Description
token_type	Always “Bearer”
expires_in	Token validity in seconds (typically 1 hour)
access_token	The JWT token to use for API requests

Using the Access Token

Include the access token in the Authorization header for all API requests:

curl -X POST "https://debt-core-api-sandbox.alleviate.com/graphql" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ creditReport(id: \"123\") { id status } }"}'

Token Management Best Practices

Token Caching

Cache your access token and reuse it until it expires. Requesting a new token for every API call adds unnecessary latency.

1. Cache tokens - Store the token and reuse until expires_in seconds pass
2. Refresh proactively - Request a new token ~5 minutes before expiration
3. Handle 401 errors - If you receive a 401, request a new token and retry
4. Secure storage - Never expose client secrets in client-side code

Troubleshooting

Common Authentication Errors

Error	Cause	Solution
invalid_client	Incorrect client ID or secret	Verify your credentials
invalid_scope	Wrong scope specified	Use the correct API scope
unauthorized_client	App not authorized	Contact Alleviate to grant permissions
expired_token	Token has expired	Request a new access token

Next Steps

Once you have authentication working:

1. Review the Environments to select the right endpoint
2. Follow the Full Enrollment Flow to make your first API calls