Skip to content

User Experience - Authentication

The Cardlytics Mobile SDK and Web Experience both need to have the authentication of your users validated by your servers. Authentication needs to be implemented by your servers which will use a Cardlytics assigned private secretKey to generate and sign a well-formed JWT. This JWT is what the Cardlytics Mobile SDK and Web Experiences will use to validate the authentication of your users as they move between your experience and the Cardlytics provided rewards experience.

Your servers will generate JWTs as described below in response to your application's request.

Info

This example includes new lines and spaces for readability. The actual JSON used to produce the token should not include this formatting white space.

Info

Also note there is a requirement that your servers validate the authenticity of requests from your experience (mobile app, web) to your servers. Your servers should only issue JWTs to authenticated users of your applications.

Info

Your app should never ship with the secretKey nor be provided with the secretKey by your servers or any other mechanism.

JWT Payload

For more details, see: the API Reference: Overview: Cardlytics JWT Authorization Token.

Cardlytics requires the following standard attributes in your JWT payload:

  • iss - (Issuer) The applicationId assigned by Cardlytics. Example: cdlx:dddddddd-dddd-dddd-dddd-dddddddddddd
  • sub - (Subject) The unique userId you have assigned to your user. Example: 00000000-0000-0000-0000-000000000000
  • exp - (Expiration) The expiration date of the token expressed in seconds since epoch. This should be less than 1 hour. Example: 1590598276
  • jti - (JWT ID) A randomly generated unique id for the token, typically a uuid. Example: eeeeeeee-ffff-eeee-ffff-eeeeeeeeeeee

For the Web Experience, there is an additional field that must be set: rnw (renew).

  • rnw - (Renew) A fully secure URL that will be used to redirect the user to your reauthentication page. We will also include a redirect query parmeter in your reauthentication URL which should be used to send the user back to their previous location inside the Cardlytics Powered By experience once reauthenticated. Example: https://my.website/?redirect=offer_map For more details see: Reauthentication (For Web Only)

Example: Mobile SDK

header: 

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

payload:

Info

The server generates a unique jti and calculates an exp of 1 hour in the future and includes them in the json payload for the JWT.

1
2
3
4
5
6
{
  "iss": "cdlx:dddddddd-dddd-dddd-dddd-dddddddddddd",
  "sub": "00000000-0000-0000-0000-000000000000",
  "exp": 1584286259000,
  "jti": "eeeeeeee-ffff-eeee-ffff-eeeeeeeeeee2"
}

The signature code: 

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

token (this is the JWT to be passed to the Cardlytics Mobile SDK or Web Experience)

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkZGRkZGRkZC1kZGRkLWRkZGQtZGRkZC1kZGRkZGRkZGRkZGQiLCJzdWIiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJleHAiOjE1ODQyODYyNTkwMDAsImp0aSI6ImVlZWVlZWVlLWZmZmYtZWVlZS1mZmZmLWVlZWVlZWVlZWVlMiJ9.xe7SR7l7X4pVXETsUS0XIfaWK4gD8cf1VTCo0bKagDs

Example: Web Experience

header: 

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

payload:

Info

The server generates a unique jti and calculates an exp of 1 hour in the future and includes them in the json payload for the JWT. The server also includes the rnw field which indicates where the Cardlytics Web Experience can query to retrieve an updated JWT. For more details see: Reauthentication (For Web Only)

1
2
3
4
5
6
7
{
  "iss": "cdlx:dddddddd-dddd-dddd-dddd-dddddddddddd",
  "sub": "00000000-0000-0000-0000-000000000000",
  "exp": 1584286259000,
  "jti": "eeeeeeee-ffff-eeee-ffff-eeeeeeeeeee2",
  "rnw": "https://my.auth.servers/renewJWT"
}

The signature code: 

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

token (this is the JWT to be passed to the Cardlytics Mobile SDK or Web Experience)

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkb3NoOmRkZGRkZGRkLWRkZGQtZGRkZC1kZGRkLWRkZGRkZGRkZGRkZCIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsImV4cCI6MTU4NDI4NjI1OTAwMCwianRpIjoiZWVlZWVlZWUtZmZmZi1lZWVlLWZmZmYtZWVlZWVlZWVlZWUyIiwicm53IjoiaHR0cHM6Ly9teS5hdXRoLnNlcnZlcnMvcmVuZXdKV1QifQ.Vx4RMPp-0DMm5zCx2TWM67U9Ja5-cO533xZNKQm_Ofo

Reauthentication (For Web Only)

When a user's JWT expires it will be necessary for us to get a new JWT for them to continue their experience. While the mobile SDK's have callbacks to handle this situation, the web experience uses a slightly different paradigm. To reauthenticate your users on web, simply set a URL in the rnw field of your JWT. That URL will be used to redirect the user to your reauthentication page. We will also include a redirect query parmeter in your reauthentication URL which should be used to send the user back to their previous location inside the Cardlytics Powered By experience once reauthenticated.

Example

https://my.website/?redirect=offer_map

Once the user is done reauthenticating, simply redirect the user back to the Cardlytics Powered By Web experience and pass in their new JWT like you would with regular authentication. Then append their previous location to the URL as a query param with the identifier redirect.

Example

https://poweredby.dosh.com/partners/yourName/setup/${encodedPayload}?redirect=offer_map