Generic entitlement interface

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 https //github com/purplepublish/generic entitlement sample https //github com/purplepublish/generic oauth entitlement sample api specifications username / password for username / password entitlements there are four main operations to implement in your backend service login 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 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 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 entitlements 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 https //github com/purplepublish/generic entitlement sample/blob/main/src/main/kotlin/com/sprylab/purple/example/model/userentitlement kt 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 entitlements 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 https //github com/purplepublish/generic oauth entitlement sample/blob/main/src/main/kotlin/com/sprylab/purple/example/model/userentitlement kt 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 universal identifier universal description unlocks all contents of the app contents with ids identifier content ids description unlocks specific contents based on purple content ids (id field of content in catalog api) contents with custom properties identifier content properties description unlocks specific contents based on the custom properties of the content contents with custom property x identifier content property values description unlocks specific contents based on the values of a custom property of the content contents with tags identifier content tags description unlocks specific contents based on the tags publication with id identifier publication date description unlocks the contents of a publication within a date range and optionally limited to week days within that range publications with ids identifier publication ids description unlocks the contents of multiple publications (optionally limited to week days) publications with external ids identifier publication external ids description unlocks the contents of publications based on their external id (optionally limited to week days) publications with custom properties identifier publication properties description unlocks the contents of publications based on their custom properties (optionally limited to week days)