Customers Support What's new

Prenly Remote API - Internal

Art. no. 217681177

What is Prenly Remote API? 

Prenly Remote API creates a real-time connection between Prenly and the publisher's own login system, as it allows publishers to integrate their own authentication and authorization systems with Prenly’s platform. When a user logs into the e-magazine, a query is sent to the publisher's system to verify the user and check rights. The answer is stored in Prenly in order to keep the user logged in. Prenly sends a new query to the publisher's system at certain intervals to check the user's rights. 

Per-publication access

With the new development the remote API now also enables per-publication access. 

Definitions:

  • Authentication​ is the process of someone trying to prove who he or she is. Normally, this is made by providing some credentials such as a username and a password.
  • Authorization​ is the process of deciding what resources a known user has access to. For Prenly this is normally a user wanting to read a newspaper.
  • An ​API​ (application program interface) is a set of routines, protocols and tools to handle interaction between different systems or parts of systems.

What is it used for? / What are its features? 

  1. Custom Authentication: It allows publishers with existing login systems to use their own user credentials (e.g., username and password) for accessing the Prenly e-newspaper. This means that user management, such as account registration and password recovery, can remain within the publisher’s system.
  2. Real-Time Authorization and Access Control: Through the API, publishers can perform real-time checks to confirm a user’s subscription status, granting immediate access to the e-newspaper if the user is verified as a subscriber.
  3. Flexible Integration: The API allows publishers to implement specific web services that Prenly can call to verify credentials, check permissions, and retrieve user subscription data. This integration is adaptable to various scenarios, including server-to-server authentication and OAuth2 setups.
  4. Api authentication: Prenly ensures secure communication with the publisher’s system by requiring authentication credentials for each request. Depending on the integration type, this may involve shared secrets and client credentials

Integration Methods

Variant 1: External OAuth2 login form hosted on your web page
The API supports OAuth2 for single sign-on (SSO), enabling integration with third-party identity providers and allowing readers to sign in through a single interface for multiple services. Note that the Remote api is used in a different way when it is a submodule to OAuth2. This represents a different implementation flow.

The Prenly Remote API and OAuth2 can work together but have different roles. The Remote API is used to access and manage data on the Prenly platform, while OAuth2 ensures secure and easy sign-ins. With OAuth2, the API supports single sign-on (SSO), letting readers log in through one interface for multiple services using third-party identity providers. When the Remote API is used as part of OAuth2, it works differently, focusing on handling logins and validating access rather than direct data access. This shows how the Remote API adjusts to fit the chosen setup.

Variant 2: Prenly built-in login form - login credentials are validated by your system

By implementing specific API endpoints, publishers can manage user logins and subscription-based access directly through their existing systems, ensuring seamless integration with Prenly’s applications. The application has the Remote api authority, which means we will login users via the customer's system, sending username and password there. Prenly will fetch subscriptions from that system. This is the most common variant chosen by the customer. This integration is especially suitable for publishers who already have a login system on their site.

Variant 3: Variant 3: Prenly built-in login form - login credentials are validated by Prenly

The application has the Prenly authority, so login accounts are handled by Prenly, but fetching subscriptions is made with external api requests. The customer can themselves build this api with which we will ask for subscription information. Usernames and passwords are securely stored and verified within Prenly's technical environment, while your system provides Prenly with subscription information to ensure that only subscribers can access protected content.

This option is suitable when you have users with subscription information in your own system, but lack a system to handle login accounts.
The login process for readers will be the same as when using the CSV file. They will have to create an account in Prenly. Then their account will have to be activated. 

Per-publication access

Readers can be given access to only a limited amount of the content instead of all publications. This solution makes it possible to give access to a larger period, as well as single purchases. 

It also ensures readers maintain access to publications they were entitled to during their subscription period, even after the subscription ends.

Technical details 

Common Remote API functionality 

If a product code exists in productCodes, the user gets access to all publications in that package.

{
 "uid": "string",
 "customerNumber": "string",
 "email": "string",
 "givenName": "string",
 "familyName": "string",
 "productCodes": [
   "string"
 ],
 "metaData": {
   "favoriteTitleSlugs": [
     "string"
   ],
   "marketingCloudSubscriberKey": "string"
 }
}

Limited Product List
If a product code exists in limitedProductList, the user gets access only to publications with a publication date between the validFrom and validTo dates.

"limitedProductList": [
       {
           "productCode": "string",
           "validFrom": "date",
           "validTo": "date"
       }
   ]

Trusting Prenly requests

Prenly sends a secret key in all requests. The key is known only by Prenly and your system. For all API requests, you should check that the provided key matches the expected key.

You can also open up your endpoints for certain IP addresses only. Requests from Prenly are currently done from ​192.121.104.8,​ ​192.121.104.199​ or ​192.121.104.201.​

Allow for a RESTish behaviour

Prenly requests are currently med with HTTP POST, but the API should not be limited to use any http methods for future endpoint expansion.

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.


How is the Remote API implemented? - What actions are needed from us?

Supply the customer with the documentation and ask them which variation they choose to implement. Based on this decision request the corresponding credentials from them. 

The first step after receiving the credentials is to test the integration details with the test account provided. 

In PWS: 

  • Create a new integration 
    • Click on settings → Integrations → Select custom remote API → click add
    • Fill in the information received by customer

In Superadmin:

  • Create an authority 
    • On Customer level → scroll down to Authorities → click add 


  • Then connect the authority to the application
    • On Application level scroll down to “Authority” and click on edit
    • Select the authority created previously 

 

How is the Remote API implemented? - What actions are needed from the customer?

Prenly requires publishers to implement their API endpoints according to a specification provided by us. This approach ensures compatibility with the Prenly platform, simplifies troubleshooting  and allows us to maintain and develop a single integration standard.

The customer should follow the documentation received from Onboarding to set up the Remote API. The customer should test their setup based on this documentation and the credentials with the Remote API tester before sending them to Onboarding. Helpdesk will also test the API when completing the process on our side.

When completed they need to send us the following credentials based on which variant they chose to implement: 

Credentials we always need from customer/supplier

  • A shared (secret) key 
  • Product codes to authorise access
  • Test account with an active subscription, hello@prenly.com
  • The length (in minutes) that fetched user data should be cached in Prenly (recommendation = 30 minutes) 

Variant 2: The readers will login using customer accounts

  • Remote URL to an endpoint authenticating a user by login credentials
  • Remote URL to an endpoint authorizing a user unique user ID (UID)
  • URL to create account
  • URL to forgot password 
  • URL to “missing subscription” 
  • URL to delete account (if native and create account) 

Variant 3: The readers will login using Prenly accounts

  • Remote URL to an endpoint authorizing a user by e-mail address
  • Remote URL to an endpoint authorizing a user by customer number
  • URL to "missing subscription"
  • URL to delete account (if native and create account)

Per-publication access

Defining Periods

  • If a user has access to 10 consecutive issues, one period will be sent, not 10 individual ones.
  • If there are gaps in access (e.g., 10 consecutive issues, a gap, then 5 more issues), send two periods.
  • For a single-issue purchase, send the period as a single day.

Why Periods?

Using periods reduces system load and enhances performance by avoiding the handling of hundreds or thousands of individual dates.

Handling Ongoing and Expired Subscriptions

  • If the subscription has a known end date, include it in the API call (e.g. validTo: 2024-12-31).
  • If the subscription is ongoing, use one of the following:
    • Provide an arbitrary future date (e.g validTo: 2099-12-31), or
    • leave the end date empty (validTo as null or left blank), indicating no defined end date yet.
  • When a subscription ends or a user stops purchasing new publications: send an updated period with a defined end date.

Related Links

© Textalk

We use DeepL and ChatGPT for translations. Occasional imprecisions may occur.