Richie Entitlements API

Richie apps will call Entitlements API provided by the publisher each time they are launched or brought to the foreground. Publisher's backend should validate and refresh user's token, returning it with data used for user messaging and analytics.

Request

• Method: GET

• Headers:

Authorization: Bearer <jwt-token>

Response

HTTP 200

Returned when JWT Token given in request was valid, and associated with an existing user.

{
  "analytics_data": {
    "anykey": "anyvalue"
  },
  "token": "jwt-token-data-blob"
}

analytics_data

analytics_data object contains the data which needs to be exposed to HTTP analytics (e.g. Google Analytics) and/or to HTML/JS running in Article and Paywall WebViews. The app will persist this object. This data won't be sent to Richie backend systems. Return an empty object if there is no analytics_data.

token

The refreshed JWT token. Format of the payload:

{
  "sub": "5C4BAD90-4A47-4099-B1C1-3931A8CF5CEA",
  "iat": 1582281054,
  "exp": 1592281054,
  "iss": "com.media.publisher",
  "ent": [
    "subscriptionProductA",
    "subscriptionProductB"
  ]
}

The token must be signed with private key using ES256 or ES384 algorithm. Public key will be installed on Richie's infrastructure.

sub

Subject of the JWT (the user). Since user identifiers are considered as personal data under GDPR, this field must contain only identifiers which are considered as pseudonymous personal data (UUIDs, hashes etc). Direct personal data such as e-mails or usernames must not be exposed.

iss

Issuer of the JWT. Free-form field to identify the backend which issued this token. The recommendation is to use reverse domain name notation.

ent

This is an array of product names which determines entitlements of the user. Each ent value is mapped to a subset of content in Richie platform's configuration.

HTTP 401

Returned if:

• JWT Token was invalid (e.g. invalid signing, invalid format, expiration date too far behind etc)
• JWT Token wasn't associated with any existing user

Log out on 401

By default, HTTP 401 response does not cause clients to log out. Clients will retry entitlement refreshes on the next app session.

Entitlements backend can force the clients to log out on 401 by including a custom HTTP response header: richie-logout: 1.