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 all try to adhere to and honor standard HTTP status codes. Below are the response codes that you may see when calling Cardlytics's endpoints and webhooks.

  • 200 OK - Success. The request is understood and acknowledged. The body of the response may indicate additional context or error conditions.
  • 301 and 302 - Cardlytics does not currently require clients to handle redirects. For future proofing, following 1 redirect for a request to Cardlytics is recommended.
  • 401 Unauthorized - Will be returned when the request does not include required credentials.
  • 403 Forbidden - Will be returned when the caller is not allowed to invoke the endpoint.
  • 404 Not Found - Will be returned when Cardlytics cannot locate the resource requested.
  • 405 Method Not Allowed - Will be returned when Cardlytics does not support the HTTP method requested. Note that most Cardlytics endpoints support POST only.
  • 415 Unsupported Media Type - Will be returned when Cardlytics does not understand the body of the request. Note that most Cardlytics endpoints support application/json only.
  • 429 Too Many Requests - Will be returned when 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 - Will be returned when Cardlytics emits an unknown or not-handled error.
  • 501 Not Implemented - Will be returned when Cardlytics completely does not understand the request passed.
  • 503 Service Unavailable - Will be returned if the specific service is down for maintenance or other reasons.