Authentication

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:

1. Start a session:

   • Make a POST request to /v2/session/startSession to receive a JWT, which serves as your session token.

2. Use the token in API requests:

   • For subsequent API calls, include the session token in a custom X-CDLX-Session-Token HTTP header.

3. 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.

4. 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.