Prenly Remote Authority API

The purpose of this document is to explain:

1. ...how the Prenly eco-system allows user authentication and authorization to be handled by a technical infrastructure owned by the publisher or a third party.

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

Contact

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

Definitions

Authentication is the process of verifying someone’s, or something’s, identity, as in whether they are who they say they are, before granting access to protected data. Normally this is made by providing some 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 only the “real” user would know.

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

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

In Prenly, an authority is a technical implementation deciding how authentication and authorization are handled by a Prenly application within Prenly’s backend.

Introduction

The Prenly Remote authority API introduces the ability to replace Prenly’s authorization and/or authentication handling by implementing API endpoints that follows an API specification, which enables a Prenly customer to authenticate and authorize by their system, requirements and needs.

At the core, this enables the Prenly application’s authority to authorize and/or authenticate users as they engage with the Prenly application, i.e. when they read publications within 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 users and API implementation. Instead, the API implementation informs the Prenly authority how to act upon the users’ authentications and authorization requests.

Implement your API

Understand how the user consumes the Prenly application

Prenly applications

Prenly serves the end user with applications mainly used for reading 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 may contain published publications that are public for everyone, as well as protected content that needs some kind of permission to be consumed. For native apps, it is also possible to allow any non-logged-in user to consume some publications for free before login is required.

Navigating the application

By using the application a user can normally see the start page containing components displaying published publications. Public publications can be opened and read by selecting the publication. But when the user tries to open a protected publication, the application will require the user to log in (authentication).

After logging in, Prenly will decide whether the requested publication is readable for that user (authorization). If so, the publication will be opened, ready to be consumed. If the user does not have read access, the user will be notified within the app. The protected content will not be shown, but the user will still be logged in.

In some cases, an application will require the user to log in to display certain publications, especially when not all published publications can be seen by just anyone. For example publications accessible via a subscription where other non-subscribed published publications should be hidden.

Setup an API environment

Trusting Prenly requests

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

You may also open up your API endpoints for certain IP addresses only for extra security. Please contact us for an up-to-date list of IPs Prenly will use in requests if you would like this extra security.

Encrypt the traffic

We strongly recommend disallowing any unencrypted HTTP traffic to your API. Use HTTPS!

Allow for a RESTish behaviour

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

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

Request parameters are currently passed as JSON in the request body.

All endpoints are currently responding with JSON in the response body.

Get acquainted with OpenAPI 3.0

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

Auto-generated documentation is provided 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 as a reference. With this file, you can easily build a testing environment with ready-made tools provided at https://openapi.tools/ (see the section “Testing).

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

Build the authentication endpoint

See the API specification at https://apidoc.prenly.com/remote-api/ for the authentication endpoint(s). You can choose the endpoint URL exactly as you wish; however, the endpoint must follow the API specification.

Request parameters

Request parameters are part of the request body 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 that was authenticated.

Response on failure

Known errors that depend on the given request parameters, must respond with one of the HTTP status codes 401, 403 or 412 as specified in the API documentation. These errors must include a JSON response following the Error data model which you can find specified at the bottom of https://apidoc.prenly.com/remote-api/.

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

We highly recommend that you provide a “message” property value in English that represents the error in some way. If your software has some kind of internal codes, it is suitable to use them here if future mutual troubleshooting will be needed. Do not include personal data that is not needed, such as personal names! Unique IDs are good enough to troubleshoot.

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

Build the authorization endpoint

See the API specification at https://apidoc.prenly.com/remote-api/ for the authorization endpoint(s). You can choose the endpoint URL exactly as you wish; however, the endpoint must follow the API specification.

Request parameters

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

Response on success

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

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

What properties are used to

The only property that currently cannot be left blank is “uid”. The other properties can be omitted, however, we recommend that you specify a “productCodes” property to better control if Prenly should or should not grant read-permission to publications. Currently, Prenly will treat a missing “productCodes” property as an empty list.

Response on failure

Known errors that depend on the given request parameters, must respond with one of the HTTP status codes 403, 404 or 412 as specified in the API documentation. These errors must include a JSON response following the Error data model as described above.

Testing

It is important to test your implementation for the authentication and authorization endpoints. Refer to https://docs.google.com/document/d/1UxmvDs7_Z0GwGbwCHXr4Ojpb9HaZif1nJ8YRMmztzeo/ for more information regarding testing 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 credentials are sent to Prenly’s authority (encrypted with SSL). From there, the authority handles how to use these credentials to authenticate the user. For the Remote authority API, this means that the credentials are sent to the remote endpoint according to the specification.

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

If authentication succeeded...

A successful login will trigger a separate authorization request to the authorization remote API endpoint to fetch the user’s information, which is cached in Prenly for a limited set of time.

The application will also reflect that someone is logged in, with name or email based on what user data was returned within the user information.

If credentials were wrong…

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

If something failed...

Other client or server-based errors, or network errors, is caught and logged by Prenly. The application will be served with a suitable error message to present to the user.

When the user keeps reading

Caching for repeating requests

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

Re-authorization

Prenly will use the cached result for each authorization request as long as the cache has not expired. If the cache has expired then 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.

Failure handling

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

Going live

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

Prenly will require information from you to set up your implementation in Prenly. The information will be evaluated and if everything is up to par your implementation can be used in Prenly for your chosen e-paper Prenly applications.

Setting up Prenly

Before your implementation of the remote API can be used in Prenly you must provide:

• Your chosen secret key for the authentication and authorization endpoints

• Your chosen API endpoints

• A list of products that should grant read-permissions and for which Prenly title (only Prenly-known products within the product codes list from the authorization endpoint can grant read-permission)

• Your desired cache expiration time

• 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 (in case they forgot their password)

• We recommend that you also provide a URL where an authorized user without any Prenly-known product codes may activate a product (i.e. 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 your e-paper’s Prenly authority