Reading Permissions

Our system can be setup to check the reading permissions for individual users based on the data of an external system.

To use this feature, you will need to:

  1. Generate an API integration key on your library dashboard.
  2. Set-up your external system to make requests to publica.la servers.
  3. Enable the feature in your library dashboard.
  4. Provide a fallback endpoint in case we don't have data registered.

Get your API Key

Go to the library Dashboard -> Settings -> Integrations and generate your API integration key. This key will be tied to your user. Do not share it!

Make requests to define your users access

You can give your user access to individual publications and collections. For this, you will have to make a POST request where you tell us the user and the data he must have access to.

Request

POST to https://{{your_library_domain}}/integration-api/v1/reading-permissions

Headers

{
  "Content-Type": "application/json",
  "Accept": "application/json"
}

Body:

{
  "user_external_id": "user_external_id",
  "user_email": "user@email.com",
  "issues_external_ids": ["r4asJKDP785w", "snBDRZOa6u8E"],
  "issues_collections": ["coleccion-1", "coleccion-2"],
  "user_token": "your_api_token"
}

where:

  • user_external_id: string, nullable
  • user_email: string, email, nullable
  • issues_external_ids: array of ISBN, can be empty
  • issues_collections: array of collections names, can be empty
  • user_token: Your API integration key, required

Take into account:

  • We need at least a way to identify the user, so make sure to send at least one of this two fields: user_external_id or user_email.
  • issues_external_ids and issues_collections must be both arrays of strings.
  • You can overwrite the user access making another request.

Provide a fallback URL

If we don't have data for a particular user, we will attempt to make a request to your servers to get the data.

The system executes a GET request, the request will include the email (URL encoded) and external_id of the user in the query string, for example:

https://{your_external_domain}/api/v1/permisos-de-lectura?user_email=juan@gmail.com&user_external_id=ee8a8cb5-9cff-442c-9d78-3e65cc10b114

The system currently doesn’t supports authentication methods that involve dynamic credentials or with expiration (as JWT).

It’s recommended for the responses to take at most 100ms, in order to ensure a good user experience. A 10 seconds timeout will be applied, after which the request will be considered failed.

The response must consist of an object as the following:

{
  "issues_external_ids": ["r4asJKDP785w", "snBDRZOa6u8E"],
  "issues_collections": ["coleccion-1", "coleccion-2"]
}

Where:

  • issues_external_ids: array of ISBN, can be empty
  • issues_collections: array of collections names, can be empty

In the case of a timeout or an error in the validation of the response, the system will only allow the user to access free publications.

Enable it

Go to the library Dashboard -> Settings -> Integrations and tick the option Enable reading permissions. Make sure to provide the Fallback URL.