Log into external services with RERO ILS (OAuth)

  • api
Last updated: 03-06-2024

This document describes the RERO+ authentication service based on the OAuth2 protocol. It is used to authenticate readers of the RERO+ network, for example in external services that provide resources to library users.

For information on how this protocol works, see:

Get access

You must make a request to the RERO ILS system admin to obtain the access parameters for the authentication server. To do this, you must provide:

  1. the name of the service
  2. a contact person and their e-mail address
  3. a redirect URL (ex: https://your_domain/authorize).

As soon as your registration is complete, you will receive your client_id and your client_secret.


  • Authorization endpoint for RERO+: https://bib.rero.ch/oauth/authorize
  • Token endpoint for RERO+: https://bib.rero.ch/oauth/token

Data is transmitted in JSON format. The authentication server is only accessible via HTTPS.

Token validity

  • authorization_code: 30 seconds
  • access_token: 1 hour
  • refresh_token: 30 days

Obtain an authorization code

The URL used to authenticate the patron is https://<instance>/oauth/authorize.

param value description
client_id identifier customer identification code
response_type code token return parameter (fixed value)
redirect_uri url url of your authentication service
scope [fullname, birthdate, institution, expiration_date, patron_type, patron_types] value delimited by a space. This provides additional information about the patron.

Example of an authentication URL (for readability, line breaks have been added):

GET https://bib.rero.ch/oauth/authorize?

Manipulate the response

The response is sent to the redirect_uri parameter specified in the base URL. If the patron approves access, a response is returned with an authorization code. This is used for the next request.

POST https://bib.rero.ch/oauth/token
        client_id: {CLIENT_ID},
        client_secret: {SECRET},
        redirect_uri: 'http://your_domain/authorize',
        grant_type: 'authorization_code',
        code: {CODE}

It is necessary to send the data with a POST request, as the information contained in this request is sensitive.

A valid response returns a JSON array:

    "access_token": "4NPtBhoiBmML6k7cDe9RdcrXrHl7XR",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "fullname birthdate institution expiration_date patron_type patron_types",
    "refresh_token": "iic37JVAq71uLDu3jzHWdT958qh01D"
param description
access_token the token sent by the server
expires_in token validity period
token_type token type (Bearer is the only value used)
scope list of scopes sent by the request
refresh_token refresh token

The access token can be used throughout its lifetime (1 hour). Once it has expired, you must use the refresh token to obtain a new one.

Renew the access token

The refresh token is used to renew an expired access token.


The response is:

    "access_token": "2ZERNCx1x4gGcvoh51z2YTFxFPFCfY",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "fullname birthdate institution expiration_date patron_type patron_types",
    "refresh_token": "mZWszhdCb6T50l0sJYZOZQaQddrL2F"

If the refresh token has also expired, you must go back to Obtain an authorization code.

API call

After obtaining the token, you can make a request to the API in this form:


Depending on the scopes, you'll get a response like this

  "barcode": "xxxxxxxxxxx",
  "fullname": "Jean Simon",
  "birthdate": "2000-01-01",
  "patron_types": [
        "patron_type": "xx-xx",
        "institution": "VS"
        "expiration_date": "2020-03-30T15:00:00+02:00"
        "patron_type": "xx-xx",
        "institution": "FR",
        "expiration_date": "2017-07-16T20:00:00+02:00"

Interoperability applications | Access MARC data (SRU)