Generic entitlement interface

11 min

Introduction

The generic entitlement allows you to connect your entitlement service to Purple.

When choosing to use this interface, Purple simply provides the interface, but the development work to connect to it needs to be done by the customer/other party.

It offers two basic authentication models:

Username / Password

OAuth 2.0 with OpenID

There are sample implementations available for both models:

Username / Password Entitlement Sample

OAuth 2.0 with OpenID Sample

API Specifications

Username / Password

For username / password entitlements there are four main operations to implement in your backend service:

Path: /v1/login

Method: POST

Request body (JSON):

Field	Type	Optional/Required
appId	String	Required
deviceId	String	Optional
username	String	Required
password	String	Optional

Response body (JSON):

Success (HTTP Status 200)

Field	Type	Optional/Required
accessToken	String	Required
userId	String	Optional

Error: Invalid credentials (HTTP Status 403)

Field	Type	Optional/Required	Values
code	String (Enum)	Required	UNKNOWN WRONG_PASSWORD_OR_USERNAME USER_DEACTIVATED AUTHENTICATION_ERROR WRONG_PASSWORD INSTALLATION_LIMIT_EXCEEDED SYSTEM_ERROR_IN_REMOTE_SYSTEM PARAMETER_ERROR_IN_REMOTE_SYSTEM
message	String	Required

Logout takes the access token from a session and performs necessary steps to end the session.

Path: /v1/logout

Method: POST

Request body (JSON):

Field	Type	Optional/Required
appId	String	Required
deviceId	String	Optional
accessToken	String	Required

Response body (JSON):

Success (HTTP Status 200)

No response body

Error: Invalid credentials (HTTP Status 403)

Field	Type	Optional/Required	Values
code	String (Enum)	Required	UNKNOWN AUTHENTICATION_ERROR SYSTEM_ERROR_IN_REMOTE_SYSTEM PARAMETER_ERROR_IN_REMOTE_SYSTEM
message	String	Required

Verify takes an active access token, verifies that the session is still valid and optionally returns a rotated/updated access token back to the client.

Path: /v1/verify

Method: POST

Request body (JSON):

Field	Type	Optional/Required
appId	String	Required
deviceId	String	Optional
accessToken	String	Required

Response body (JSON):

Success (HTTP Status 200)

Field	Type	Optional/Required
accessToken	String	Required
userId	String	Optional

Error: Invalid credentials (HTTP Status 403)

Field	Type	Optional/Required	Values
code	String (Enum)	Required	UNKNOWN WRONG_PASSWORD_OR_USERNAME USER_DEACTIVATED AUTHENTICATION_ERROR WRONG_PASSWORD INSTALLATION_LIMIT_EXCEEDED SYSTEM_ERROR_IN_REMOTE_SYSTEM PARAMETER_ERROR_IN_REMOTE_SYSTEM
message	String	Required

The Entitlements endpoint takes an active access token, verifies that the session is still valid and returns a list of entitlements the user has. Please see the sample code for all possible entitlement models.

Path: /v1/entitlements

Method: GET

Request params:

Field	Type	Optional/Required
appId	String	Required
deviceId	String	Optional
accessToken	String	Required

Response body (JSON):

Success (HTTP Status 200)

List of JSON objects. Each object must have a "type" field with one of the following options:

universal

content_ids

content_properties

content_property_values

content_tags

publication_id

publication_ids

publication_external_ids

publication_properties

Please see the following documentation regarding the description of each type.

Error: Invalid credentials (HTTP Status 403)

Field	Type	Optional/Required	Values
code	String (Enum)	Required	UNKNOWN USER_DEACTIVATED AUTHENTICATION_ERROR SYSTEM_ERROR_IN_REMOTE_SYSTEM PARAMETER_ERROR_IN_REMOTE_SYSTEM
message	String	Required

OAuth 2.0 with OpenID

For the OAuth 2.0 with OpenID entitlement you need an OAuth 2.0 / OpenID authentication server, e.g. Keycloak, and a server for with an endpoint to provide the user entitlements, like the username / password entitlement does.

Path: /v1/entitlements

Method: GET

Request headers:

Authorization

The access token is provided as a Bearer token

Request params:

Field	Type	Optional/Required
appId	String	Required
deviceId	String	Optional

Response body (JSON):

Success (HTTP Status 200)

List of JSON objects. Each object must have a "type" field with one of the following options:

universal

content_ids

content_properties

content_property_values

content_tags

publication_id

publication_ids

publication_external_ids

publication_properties

Please see the following documentation regarding the description of each type.

Error: Invalid credentials (HTTP Status 403)

Field	Type	Optional/Required	Values
code	String (Enum)	Required	UNKNOWN USER_DEACTIVATED AUTHENTICATION_ERROR SYSTEM_ERROR_IN_REMOTE_SYSTEM PARAMETER_ERROR_IN_REMOTE_SYSTEM
message	String	Required

Entitlement types

Identifier: universal

Description: Unlocks all contents of the app

Identifier: content_ids

Description: Unlocks specific contents based on Purple Content IDs (id field of content in Catalog-API).

Identifier: content_properties

Description: Unlocks specific contents based on the custom properties of the content

Identifier: content_property_values

Description: Unlocks specific contents based on the values of a custom property of the content

Identifier: content_tags

Description: Unlocks specific contents based on the tags

Identifier: publication_date

Description: Unlocks the contents of a publication within a date range and optionally limited to week days within that range.

Identifier: publication_ids

Description: Unlocks the contents of multiple publications (optionally limited to week days)

Identifier: publication_external_ids

Description: Unlocks the contents of publications based on their external ID (optionally limited to week days)

Identifier: publication_properties

Description: Unlocks the contents of publications based on their custom properties (optionally limited to week days)

Generic entitlement interface

Introduction

API Specifications

Username / Password

logout

verify

entitlements

OAuth 2.0 with OpenID

entitlements

Entitlement types

Universal

Contents with IDs

Contents with custom properties

Contents with custom property X

Contents with Tags

Publication with ID

Publications with IDs

Publications with External IDs

Publications with custom properties