You are here: Tutorials > Authenticating with the Patron API

Authenticating with the Patron API

The following tutorial gets you up and running with the Sierra API authorization endpoint to authenticate with a Sierra server.

In addition to bibliographic and item data access, the Sierra API provides transactional APIs for placing holds and updating patron accounts. It incorporates two independent options that affect access to patron data; Global Patron Access and Patron-specific Authentication. When library staff generate API keys in the Sierra Administration Application, they choose which patron record access permissions to apply to each new key.

API KEY GENERATION OPTIONS

Patron Read + Patron Write

Patron-specific Authentication Patron Record Access OAuth 2.0 Flow
    No access to patron data Client Credentials Grant
x   Read and update any patron record using the API. Client Credentials Grant
  x Read and update only specific patron records using the API. Patrons must authenticate using their credentials, such as barcode or PIN. Authorization Code Grant
x x Read and update any patron record or specific patron records using the API. Patrons can be authenticated using their credentials, such as barcode or PIN. Client Credentials Grant and Authorization Code Grant

Libraries generate and issue API keys with the level of patron record access appropriate to the use case of the intended application. The API’s OAuth 2.0 Client Credentials Grant and/or Authorization Code Grant flows support the available access levels.

An application using the API must authenticate itself with the Sierra system before it receives access to any of the API endpoints. The following steps show you how to authenticate your application using the Client Credentials Grant. You can download the Advanced REST Client Chrome plug-in, or a similar REST client, to try it for yourself.

  1. Obtain an API key and secret. This example uses an API key issued for Innovative's sandbox at https://sandbox.iii.com:

Key: WO0rS+IFzwLnso/kmPGM6S9h5Lv8 Secret: pleaseletmein

  1. Combine the API key and secret into a single string, but separate them with a colon:

WO0rS+IFzwLnso/kmPGM6S9h5Lv8:pleaseletmein

  1. Convert the combined key:secret string into a Base64 string. Software libraries that do this conversion are available in most programming languages. Since this example uses the Advanced REST Client to make calls to the API, we'll use the Base64 Encode and Decode online utility.

The original key:secret string

WO0rS+IFzwLnso/kmPGM6S9h5Lv8:pleaseletmein

becomes

V08wclMrSUZ6d0xuc28va21QR002UzloNUx2ODpwbGVhc2VsZXRtZWlu

after it has been Base64 encoded. This encoded string serves as our credentials when we authenticate with the Sierra API.

  1. Launch the Advanced REST Client.
  2. Set the URL to:

https://sandbox.iii.com/iii/sierra-api/v3/token

  1. Set the method to Post.
  2. In the Headers section, choose Raw, and then add the following header:

Authorization: Basic <insert your Base64 encoded credentials from step 3>

Our example header is:

Authorization: Basic V08wclMrSUZ6d0xuc28va21QR002UzloNUx2ODpwbGVhc2VsZXRtZWlu

  1. In the Payload section, choose Raw and set the HTTP body to:

grant_type=client_credentials

  1. Click the Send button (on the lower-right).

  1. If the authentication is successful, the API returns a status of 200 and an access token in the response body. This access token is what we use to make subsequent calls to the API for access to Sierra data.

In the next tutorial, we’ll use the access token to make an API call.