Starting a Session & Scopes for API Access

Follow the steps outlined here.

Step 1. Start a session by obtaining a session token.

A session token is an encoded JSON Web Token representing the institution and customer metadata relevant to a session.

1	`POST /v2/session/startSession`

Important

Session tokens should be cached. The API may return a 401 response, but there will be no special indication that the session has expired. (Note that this is a security best practice.)
It is acceptable for a user to have multiple sessions. It is also acceptable if the token is stored in some session that is maintained for the end user.

Step 2. After requesting a session token, set it as a custom X-CDLX-Session-Token HTTP header in your subsequent API requests.

Example: cURL Request with SessionToken in Custom HTTP Header

The following example shows a session token being set as an HTTP header. An X-CDLX-Request-Id header is also being set for debugging and tracing.

% curl -X POST \
  -H 'X-CDLX-Request-Id: 56d5d70e-7fb8-43d3-8331-19bb6930bbdb' \
  -H 'X-CDLX-Session-Token: ${token}' \
  publisher-uk-fiuat.cardlytics.com/v2/ads/getAds

Session Expiration

When a session expires, you will receive a 401 Session Expired response from Cardlytics. In this case, request a new token by making another /startSession API call.

Token scopes and API access

You specify one or more scopes depending on the APIs you need to access.

These scopes will be encoded into a scope claim on your token to specify the token's intended usage.

Institution-level scope

Use this type of token to interact with APIs that are broadly scoped to the level of an institution, in cases where no specific customer context is required.

Scopes

Scope	APIs	Description
`api:institution`	Data APIs	Create or update your institution's customer data, as well as their account and card information
`api:institution`	Data APIs	Send Cardlytics transaction information from your institution

Customer-level scope

Use this type of token to interact with APIs that are intended to be accessed on behalf of a customer. In this case, a sourceCustomerId must be specified as well.

Scopes

Scope	APIs	Description
`api:customer`	Ads	Access targeted ads in the scope of a specific customer
`api:customer`	Customer Profile APIs	Allows customers to view their own profile
`api:customer`	Events APIs	Log events and interactions that take place throughout a customer's session

Request

The request body should contain a JSON object with the following properties:

Property	Type	Required	Description
scopes	string[]	Required	Array of requested scopes
organizationId	string	No	ID of a subsidiary of an institution
sourceCustomerId	string	Required for Customer-level scopes only	Publisher-issued customer ID

Response

Property	Type	Description
sessionToken	SessionToken	Encoded session token

Examples

Customer-level Scope Example

In this example, a token is being requested on behalf of a customer. The specified scopes will allow the token bearer to browse ads and customer profile information, and to log events and interactions.

1	`POST /v2/session/startSession`

{
    "scopes": ["api:customer"],
    "sourceCustomerId": "520b3ebc-6496-47f0-863e-d95d667b0cda"
}

Response

{
    "sessionToken": "ZDk5NWJmYWYtOTdiNC00YWM4LThhMTYtNGRmY2FjZTk4Yzcw"
}

Institution-level Scope Example

In this example, a token is being requested in order to interact with institution-level API resources. The specified scopes will allow the token bearer to create or update customers, accounts, and cards, as well as notify Cardlytics of transactions.

1	`POST /v2/session/startSession`

{
    "scopes": ["api:institution"]
}

Response

{
    "sessionToken": "eyJrZXlWZXJzaW9uSWQiOjEsImFsZyI6IkhTMzg0In0"
}