Prenly Remote Authority API

The purpose of this document is to explain:

1. ...how the Prenly ecosystem allows to manage authentication and authorization of users using a technical infrastructure owned by the publisher or a third party.

2. ...how a technical implementation can be done by building a modest residual API that follows the "Prenly Remote authority API" specification.

Contact

Please contact us by email at hello@prenly.com or by phone at +46-31-3884740 for questions or concerns regarding this API.

Definitions

Authentication is the process of verifying the identity of someone or something, i.e. whether they are who they claim to be, before access to protected data is granted. Normally, this is done by providing certain credentials, such as a username and a password. Given that the credentials match a stored record, the user is "verified" (authenticated) by applying the principle that the user knew something that only the "real" user would know.

Authorization is the process of determining what resources a user has access to, i.e. what data the user is authorized to access and what the user may or may not do. For Prenly, this means determining which publications the user can see and open to read.

An API(Application Program Interface)is a set of routines, protocols and tools to manage the interaction between different systems or parts of systems, and dictates the communication between systems.

In Prenly, an authority is a technical implementation that determines how authentication and authorization are handled by a Prenly application in the Prenly backend.

Introduction to the

The Prenly Remote Authority API provides the ability to replace Prenly's management of authorization and/or authentication by implementing API endpoints that follow an API specification, allowing a Prenly customer to authenticate and authorize based on their system, requirements, and needs.

Basically, this allows the Prenly application authority to authorize and/or authenticate users when they interact with the Prenly application, i.e. when they read publications in an app, by proxy of the Prenly Remote Authority API.

The Prenly authority will mediate authentication and authorization requests between users and Prenly where no direct communication is allowed between user and API implementation. Instead, the API implementation informs the Prenly authority how to act on users' authentication and authorization requests.

Implementing your API

Understand how the user uses the Prenly application

Prenly applications

Prenly provides the end user with applications that are mainly used to read publications and articles. The application is either a native mobile app on the Android or iOS platform or our responsive web-based e-reader. These two application types offer a similar user experience.

The application can contain published publications that are public to all, as well as protected content that requires some form of permission to be consumed. For native apps, it is also possible to allow all non-logged-in users to consume certain publications for free before login is required.

Navigating the application

When a user uses the application, he or she can normally see the home page which contains components that display published publications. Public publications can be opened and read by selecting the publication. However, when the user tries to open a protected publication, the application will require the user to log in(authentication).

After logging in, Prenly determines if the requested publication is readable for that user(authorization). If so, the publication will open and be ready to use. If the user does not have read access, the user is notified in the app. The protected content will not be displayed, but the user will still be logged in.

In some cases, an application will require the user to log in to view certain publications, especially when not all published publications can be viewed by anyone. For example, publications available via a subscription where other published publications that are not subscribed should be hidden.

Configuring an API environment

Trust for Prenly requests

Prenly sends a predefined secret key in all authentication and authorization requests. The key is only known by Prenly and your system. You should check that the provided key matches the expected key for all API requests.

You can also open up your API endpoints to only certain IP addresses for extra security. Contact us to get an updated list of IP addresses that Prenly will use in requests if you want this extra security.

Encrypt the traffic

We strongly recommend that you don't allow any unencrypted HTTP traffic to your API. Use HTTPS!

Allow a REST-like behavior

Prenly requests are currently made using HTTP POST, but the API should not be limited to using any HTTP methods for future endpoint expansion. Please refer to the current API specification for more information as the API specification has the final say in any deviations from this documentation.

In API responses, HTTP status codes are used to inform Prenly of the result. You must be able to respond with different HTTP status codes, both for successful requests and for data errors, runtime errors, and unexpected server errors.

Request parameters are currently sent as JSON in the body of the request.

All endpoints currently respond with JSON in the response body.

Familiarize yourself with OpenAPI 3.0

The API specification is documented in a yaml file according to the OpenAPI 3.0 standard (formerly Swagger) and specifies the technical aspects and requirements of the API and each endpoint, including all request and response data objects.

Auto-generated documentation is available at https://apidoc.prenly.com/remote-api/ and the specification file is available at https://apidoc.prenly.com/remote-api/spec/v1.3-specification.yaml.

Feel free to make a copy of the specification file and modify it to your API endpoints (URLs) as the auto-generated specification contains generic named endpoints for reference. With this file, you can easily build a test environment with ready-made tools available at https://openapi.tools/ (see the "Testing" section).

Read more about OpenAPI, including the specification, at https://www.openapis.org/.

Building the authentication endpoint

See the API specification at https://apidoc.prenly.com/remote-api/ for the authentication endpoints. You can choose the endpoint URL as you like, but the endpoint must follow the API specification.

Request parameters

Request parameters are part of the request as JSON and are sent by Prenly for each request.

Response on success

A successful login must respond with HTTP status code 200 and a JSON response with the unique identifier of the user who was authenticated.

Response on failure

Known failures due to the specified request parameters must be responded to with one of the HTTP status codes 401, 403 or 412 as specified in the API documentation. These errors must contain a JSON response that follows the Error data model found at the bottom of https://apidoc.prenly.com/remote-api/.

You can choose to provide either an Erroror an empty JSON object. Currently, only the "message" property is required if you provide an Error. However, it is recommended to also provide a "code" property.

We strongly recommend that you set a value for the "message" property in English that represents the error in some way. If your software has any kind of internal codes, it is advisable to use them here in case future mutual debugging will be needed. Do not include personal data that is not needed, e.g. personal names! Unique IDs are good enough for troubleshooting.

This information is never shown to the end user but can be logged in Prenly to simplify troubleshooting.

Building the endpoint for authorization

See the API specification at https://apidoc.prenly.com/remote-api/ for the authorization endpoints. You can choose the endpoint URL however you want, but the endpoint must follow the API specification.

Request parameters

Request parameters are part of the request as JSON and are sent by Prenly for each request.

Response on success

A successful retrieval of the user information must respond with HTTP status code 200 and a JSON response according to the UserSummary data model described in the specification.

The fields of this data object are explained at the bottom of https://apidoc.prenly.com/remote-api/.

What properties are used for

The only property that currently cannot be left blank is "uid". The other properties can be omitted, but we recommend setting a "productCodes" property to better control whether Prenly should grant read access to publications or not. Currently, Prenly will treat a missing "productCodes" property as an empty list.

Response in case of failure

Known errors resulting from the specified request parameters must be responded to with one of the HTTP status codes 403, 404 or 412 as specified in the API documentation. These errors must contain a JSON response that follows the Error data model as described above.

Testing

It is important to test your implementation for the authentication and authorization endpoints. See https://docs.google .com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ for more information on how to test your endpoints.

What happens in Prenly?

When the user logs in (authentication + authorization)

When the user requests to log in and submits the login form, the login credentials are sent to the Prenly authority (encrypted with SSL). From there, the authority manages how to use these credentials to authenticate the user. For the Remote authority API, this means that the credentials are sent to the remote connection point as specified.

Prenly will process the API response and handle both successful and unsuccessful authentication requests where the user will see an error depending on the HTTP status code of the error response. See below for more information.

If the authentication was successful...

A successful login will trigger a separate authorization request to the Authorization API endpoint to retrieve the user's information, which is cached in Prenly for a limited time.

The application will also show that someone is logged in, by name or email based on what user data was returned in the user credentials.

If the login details were incorrect...

If the request was technically successful, but the credentials were incorrect, the Prenly authority will notify the application and a message about incorrect credentials will be presented to the user.

If something failed...

Other client or server based errors, or network errors, will be caught and logged by Prenly. The program will receive an appropriate error message presented to the user.

As the user continues to read

Caching for repeated requests

Caching the response data from a successful authorization (the user's information) eliminates the need for repeated requests to the remote API to retrieve user data that rarely changes. Each Prenly customer can choose the cache expiration time, we recommend setting 30 minutes, where the minimum cache expiration time allowed is 20 minutes.

Reauthorization

Prenly will use the cached result for each authorization request as long as the cache has not expired. If the cache has expired, Prenly will trigger a new authorization request to the authorization endpoint in the remote API. This will update the user's data, such as product availability, as well as the cached data.

Handling of errors

If a server error (5xx HTTP code) occurs when reauthorization is triggered, the cache expiration time is extended by five minutes. Prenly does this to avoid users being logged out due to temporary network or server errors; the user continues to read as if nothing happened, and after five minutes a new re-authorization attempt is made. This behavior lasts as long as the server problem persists. Prenly will log such technical issues and attempt to reach the customer if this occurs.

Going live

When you think the API is ready to go live (you're done developing and testing your implementation), contact us to take the final steps.

Prenly will require information from you to configure your implementation in Prenly. The information will be evaluated and if everything is in order, your implementation can be used in Prenly for your selected Prenly e-paper applications.

Configuring Prenly

Before your remote API implementation can be used in Prenly, you need to provide:

- Your selected secret key for the authentication and authorization endpoints

- Your chosen API endpoints

- A list of products to grant read permission and for which the Prenly title (only Prenly-known products in the product code list from the authorization endpoint can grant read permission)

- Your preferred expiration time for the cache

- A URL where a new user can create an account

- A URL where a user can delete their account

- A URL where a user can reset their password (if they have forgotten their password)

- We recommend that you also provide a URL where an authorized user without any previously known product codes can activate a product (e.g. purchase a subscription)

- User credentials (username and password) for the test user, where the user is shared by Textalk, Apple and Google (if you have native apps) where at least one product code must remain active as long as the remote API is used by the Prenly authority for your e-paper