Authentication

The MLA Service 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 - Your application’s unique identifier
2. Client Secret - Your application’s secret key
3. Tenant ID - The Alleviate Azure AD tenant ID
4. Scope - The API scope for the MLA Service

Caution

Your Alleviate contact will provide API credentials for your integration.

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;
}

TypeScript

import axios from 'axios';

interface TokenResponse {
  token_type: string;
  expires_in: number;
  access_token: string;
}

async function getAccessToken(): Promise<string> {
  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<TokenResponse>(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)
    response.raise_for_status()
    return response.json()["access_token"]

Raw Body (Workflow Tools)

Token request body (x-www-form-urlencoded)

grant_type=client_credentials
&client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}
&scope=api://{DEBT_CORE_APP_ID}/.default

Credentials You'll Receive

During onboarding, you’ll receive four credentials:

• Tenant ID (alleviate_tenant_id) - Alleviate’s Azure AD tenant
• Client ID (client_app_id) - Your application’s ID
• Client Secret (client_secret) - Your application’s secret
• Debt Core App ID (debt_core_app_id) - Used for the scope

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

curl -X POST "https://leads-sandbox.alleviate.com/graphql" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation CreateLead($input: LeadInput!) { createLead(input: $input) { id resultCode } }","variables":{"input":{"firstName":"Test","lastName":"User","dateOfBirth":"1985-06-15","email":"test@example.com","homePhone":"9496779225","address1":"123 Main St","city":"Los Angeles","state":"CA","zipCode":"90001"}}}'

Python

import requests

headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json",
}

payload = {
    "query": "mutation CreateLead($input: LeadInput!) { createLead(input: $input) { id resultCode } }",
    "variables": {
        "input": {
            "firstName": "Test",
            "lastName": "User",
            "dateOfBirth": "1985-06-15",
            "email": "test@example.com",
            "homePhone": "9496779225",
            "address1": "123 Main St",
            "city": "Los Angeles",
            "state": "CA",
            "zipCode": "90001",
        }
    },
}

response = requests.post(
    "https://leads-sandbox.alleviate.com/graphql",
    json=payload,
    headers=headers,
)
response.raise_for_status()
print(response.json())

JavaScript

const axios = require('axios');

const response = await axios.post(
  'https://leads-sandbox.alleviate.com/graphql',
  {
    query: 'mutation CreateLead($input: LeadInput!) { createLead(input: $input) { id resultCode } }',
    variables: {
      input: {
        firstName: 'Test',
        lastName: 'User',
        dateOfBirth: '1985-06-15',
        email: 'test@example.com',
        homePhone: '9496779225',
        address1: '123 Main St',
        city: 'Los Angeles',
        state: 'CA',
        zipCode: '90001'
      }
    }
  },
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

TypeScript

import axios from 'axios';

const response = await axios.post(
  'https://leads-sandbox.alleviate.com/graphql',
  {
    query: 'mutation CreateLead($input: LeadInput!) { createLead(input: $input) { id resultCode } }',
    variables: {
      input: {
        firstName: 'Test',
        lastName: 'User',
        dateOfBirth: '1985-06-15',
        email: 'test@example.com',
        homePhone: '9496779225',
        address1: '123 Main St',
        city: 'Los Angeles',
        state: 'CA',
        zipCode: '90001',
      },
    },
  },
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
  }
);

console.log(response.data);

Raw Body (Workflow Tools)

GraphQL request body (application/json)

{
  "query": "mutation CreateLead($input: LeadInput!) { createLead(input: $input) { id resultCode } }",
  "variables": {
    "input": {
      "firstName": "Test",
      "lastName": "User",
      "dateOfBirth": "1985-06-15",
      "email": "test@example.com",
      "homePhone": "9496779225",
      "address1": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "zipCode": "90001"
    }
  }
}

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

Required Permissions

Your application must be granted the following permissions:

Permission	Type	Description
Lead.Write	Application	Create and submit leads
Lead.Read	Application	Read lead status

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 Quick Start to make your first API call