Start Session

Abstract

This document outlines the process for initiating and authenticating a session with the Cardlytics Publisher Rewards API via the /v2/session/startSession endpoint. It details the required authentication credentials, headers, payload structure, error handling, token management, and recommended security practices for client integration.

Summary

To start a session with the Cardlytics Publisher Rewards API, clients must send a POST request to /v2/session/startSession with a JSON payload containing their clientId and secret. The request must include the Content-Type: application/json header and an obfuscated x-source-customer-id for security, preferably using the HMAC-SHA-256 algorithm.

If a customer has not linked a card, "no-user-available" can be used as the customer ID. On successful authentication, the API returns a bearer token valid for 15 minutes, to be cached for subsequent requests. Invalid credentials result in a 500 error, while expired tokens yield a 401 response, requiring clients to request a new token. The document emphasizes securely handling the x-source-customer-id and provides guidance for error handling and token renewal.

How To Start a Session

Get Session Token (Authentication)

POST /v2/session/startSession

Hostname : https://publisher-rewards-api.cardlytics.com

To authenticate and begin your session, you'll need to provide the following credentials in a secure POST request:

Request Headers:

Content-Type: application/json
*x-source-customer-id: string

Note: Refer to the Security Requirements section on suggestions to secure the x-source-customer-id. Also for customers who have not linked a card to the platform, you can use no-user-available as the x-source-customer-id to receive a valid token.

Request Payload:

clientId: Your unique clientId provided by Cardlytics.
secret: A secure secret key shared with you by Cardlytics.

Request Payload Sample:

{
  "clientId": "String",
  "secret": "String"
}

Response

On successful authentication, the API will provide a bearer token that you can use to access our services.

Token Details:

Bearer Token Validity: The token is valid for 15 minutes from the time of issue.
This Bear Token will be cached for subsequent API calls.
Only request a new token if the previous one has expired.

Errors and Handling Expired Tokens
Providing an invalid clientId or clientSecret the API will return a 500 Internal Server Error.
If your token expires, all subsequent API requests will return a 401 Unauthorized response indicating that the session is no longer valid.
To continue accessing the API, you must request a new token using the same token generation endpoint (POST /v2/session/startSession).

Security Requirements

x-source-customer-id

It's important that the x-source-customer-id is obfuscated before passing in the header of the API calls. We suggest using the HMAC-SHA-256 algorithm to ensure security.

For example: https://www.devglan.com/online-tools/hmac-sha256-online