The authentication process uses a session token, specifically an encoded JSON Web Token (JWT), to represent institution and customer metadata for an API session. The process is as follows:

Start a session:
- Make a POST request to /v2/session/startSession to receive a JWT, which serves as your session token.
Use the token in API requests:
- For subsequent API calls, include the session token in a custom X-CDLX-Session-Token HTTP header.
Session management:
- Tokens typically expire after one hour.
- If you receive a 401 response, assume the session is expired and request a new token.
- Cache the session token as appropriate.
- Users may have multiple sessions.
Error handling:
- A 400 response with "User is not enrolled in the program" means the user has enrollmentOptInStatus: INACTIVE and can’t start a session.
- A 400 response with "User has no accounts" means no account is tied to the user attempting to start a session.

Sample Implementation (Node.js)

Below is sample code that demonstrates:

Requesting a session token (using dummy endpoints and credentials).
Performing a subsequent API call with the session token.

const axios = require('axios');

// Step 1: Request session token
async function getSessionToken(institutionId, customerId) {
  const sessionRequestBody = {
    institutionId: institutionId,
    customerId: customerId,
    // Other metadata as needed
  };

  try {
    const response = await axios.post(
      'https://publisher-uk-fiuat.cardlytics.com/v2/session/startSession',
      sessionRequestBody,
      {
        headers: {
          'X-CDLX-Request-Id': 'some-unique-uuid', // e.g., use uuid() here
          'Content-Type': 'application/json'
        }
      }
    );
    return response.data.token; // adjust if response format differs
  } catch (error) {
    if (error.response && error.response.status === 400) {
      // handle inactive user or no accounts error
      console.error(error.response.data.message);
    } else {
      console.error('Session start failed:', error);
    }
    throw error;
  }
}

// Step 2: Use session token in subsequent requests
async function getAds(sessionToken) {
  try {
    const response = await axios.post(
      'https://publisher-uk-fiuat.cardlytics.com/v2/ads/getAds',
      {}, // request body as needed
      {
        headers: {
          'X-CDLX-Session-Token': sessionToken,
          'X-CDLX-Request-Id': 'some-other-uuid'
        }
      }
    );
    return response.data;
  } catch (error) {
    if (error.response && error.response.status === 401) {
      // Session expired
      console.error('Session expired. Please start a new session.');
    } else {
      console.error('Get Ads failed:', error);
    }
    throw error;
  }
}

Key Notes:

The session token is used in a custom header, not the typical Authorization header.
JWTs usually contain encoded metadata such as user, institution, and session details, and have a cryptographic signature to prevent tampering.
Expired or invalid tokens lead to a 401 HTTP response, at which point you must fetch a new token.

Security Practices:

Never expose secret keys client-side.
Store tokens securely (in-memory, secure storage).
Never place sensitive information directly in the JWT payload.

This workflow and structure are typical of JWT-backed stateless API authentication, and the Node.js pattern of requesting and using a session token applies to most server-side languages.

What’s Next

What’s Next