Developer
Entitlement services

Generic entitlement interface

11min

Introduction

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

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:

Login takes a username/password combination and returns a token to be used for further requests.

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



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.

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 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)



Updated 11 Jul 2024
Did this page help you?
PREVIOUS
Receipt Events
NEXT
Standard Entitlement Interface
Docs powered by Archbee