Skip to content

Authentication

JSON over HTTPS

Cardlytics endpoints and webhooks all support JSON encoded request bodies submitted over HTTPS. While there are no explicit rules that Cardlytics imposes around throttling incoming requests, we do ask clients to honor HTTP 429 response codes with an exponential back-off in retries if possible.

Important Ids and Key

There are several identifiers needed for the Powered by Cardlytics platform to operate with your marketplace.

  • userId : This is a unique identifier for your user assigned by your marketplace. Cardlytics recommends a uuid format for this id. Example: 00000000-0000-0000-0000-000000000000.
  • applicationId: A uuid assigned to uniquely identify your marketplace's application. You will receive an applicationId for every webhook configured or mobile application using the SDK. Example: cdlx:dddddddd-dddd-dddd-dddd-dddddddddddd
  • secretKey: This is a secret key that only Cardlytics servers and your marketplace servers should have access to. This secret should never be exposed to your application: they are only used for signing and verifying requests. Example:your-256-bit-secret

Cardlytics JWT Authorization Token

The Powered by Cardlytics platform communicates to and from your servers via JSON over HTTPS. Cardlytics will assign an applicationId and secretKey to your integration. The applicationId uniquely identifies your marketplace's application to Cardlytics while the secretKey is used to create a JSON Web Token (JWT). JWT is an open, industry standard (RFC 7519) method for representing claims securely between two parties. There are many open source libraries which can be used to generate a JWT.

JWT Header

JWT tokens are passed as an Authorization: Bearer <token> formatted header unless otherwise noted.

JWT Payload

Cardlytics requires the following standard attributes in your JWT payload.

  • iss - (Issuer) The applicationId assigned by Cardlytics for this webhook. Example: cdlx:dddddddd-dddd-dddd-dddd-dddddddddddd
  • sub - (Subject) A hex-encoded md5 digest of the JSON request body. Example: 4b375c0634a01ce45d6e3de9379ff635
  • exp - (Expiration) The expiration date of the token expressed in seconds since epoch number. Should be no more than 60 minutes in the future unless otherwise noted by the endpoint. Example: 1590598276
  • jti - (JWT ID) A randomly generated unique id for the token, typically a uuid. Example: eeeeeeee-ffff-e eee-ffff-eeeeeeeeeeee

sub To create the sub (A hex-encoded md5 digest of the JSON request body):

  1. Capture the raw JSON request body. This should be a UTF-8 encoded string.
  2. Create an md5 hash of the request body.
  3. Generate a JWT using your secretKey setting the sub field to the md5 hash from (2)

JWT Signature

The JWT must be signed using the shared secretKey assigned by Cardlytics. Cardlytics supports using JWTs generated with the HS256 algorithm.

Example JWT

The header source to Base64Url encode. 

1
2
3
4
{
  "alg": "HS256",
  "typ": "JWT"
}

The payload source to Base64Url encode. The subject json for this example: {"example":"value"} which has an md5 hash of 4b375c0634a01ce45d6e3de9379ff635.

1
2
3
4
5
6
{
  "iss": "cdlx:dddddddd-dddd-dddd-dddd-dddddddddddd",
  "sub": "4b375c0634a01ce45d6e3de9379ff635",
  "exp": 1590598276,
  "jti": "eeeeeeee-ffff-eeee-ffff-eeeeeeeeeeee"
}

The signature code 

1
2
3
crypto.createHmac("sha256", "your-256-bit-secret")
  .update(base64UrlEncode(header) + "." + base64UrlEncode(payload))
  .digest("base64");

The following is an example JWT generated from the above data.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkb3NoOmRkZGRkZGRkLWRkZGQtZGRkZC1kZGRkLWRkZGRkZGRkZGRkZCIsInN1YiI6IjdmMTZkY2Y2OGVjMWYwZDFkZDZjMzE2NWE1NWJhNWRiIiwiZXhwIjoxNTkwNTk4Mjc2LCJqdGkiOiJlZWVlZWVlZS1mZmZmLWVlZWUtZmZmZi1lZWVlZWVlZWVlZWUifQ.RNDSifWcP5IMcmYybeh4cSBz8fBpOXYlpIKdtaUVTfw

HTTP Conventions

Cardlytics's API endpoints and webhooks adhere to standard HTTP status codes.

Below are the response codes that you may see when calling Cardlytics endpoints and webhooks.

HTTP Response Code Description
200 OK Success. The request is understood and acknowledged. The body of the response may indicate additional context or error conditions.
301 Moved Permanently
302 Found		 Cardlytics does not currently require clients to handle redirects. For future proofing, following 1 redirect for a request to Cardlytics is recommended
401 Unauthorized Request does not include required credentials
403 Forbidden Caller is not allowed to invoke the endpoint
404 Not Found Cardlytics cannot locate the resource requested
405 Method Not Allowed Cardlytics does not support the HTTP method requested. Note that most Cardlytics endpoints support POST only
415 Unsupported Media Type Cardlytics does not understand the body of the request. Note that most Cardlytics endpoints support application/json only
429 Too Many Requests Cardlytics is throttling requests from your client. Note that Cardlytics tries to never respond with this response code but may under extreme circumstances
500 Internal Server Error An unknown or not-handled error
501 Not Implemented Endpoint does not understand the request passed
503 Service Unavailable The specific service is down for maintenance or other reasons