Authorization Code Grant

Use the Authorization Code Grant flow when your application is acting on behalf of a specific resource owner (library patron). The system validates the resource owner's credentials to share individual user data with your application.

This is a redirection-based flow. The resource owner interacts with the client application, which receives incoming requests (via redirection) from the Sierra REST API. Authorization information is passed in a series of URIs.

The basic steps are:

1. Set up a Sierra REST API account:
   1. Obtain a client key. Each library administers distribution of client keys for its system.
   2. Create a client secret. (The client secret must be at least 8 characters long.)
   3. Specify a redirect URI to which the system will send the user agent once access is granted.
2. Obtain an authorization code from the Sierra REST API.
   1. The resource owner accesses your client application, which requests authorization and sends its client key.
   2. The resource owner authenticates and grants access to resources (user consent).
   3. If the resource owner grants access to resources, the Sierra REST API sends an authorization code to the redirect URI.
3. Obtain an access token from the Sierra REST API.
   1. Your client application connects to the Sierra REST API and sends the authorization code, client key, and client secret.
   2. The system returns an access token.
4. Your client application extracts the access token from the response and sends the access token with each API request.

The Sierra REST API authorization implementation does not support refresh tokens.

 

Obtaining Patron-specific Information

Authorization Code Request

1. Construct an authorization request URI.

2. In response to your authorization request, the Sierra REST API redirects to the library system's authentication server. (In many cases, this is the Sierra application server.) The resource owner authenticates with the system and grants access to resources (user consent).
3. If the resource owner grants user consent, the authorization server redirects to the Sierra REST API, which sends a response containing the authorization code to the redirect URI.

Access Token Request

The access token URL has the following form:

https://<host name>/<path>/<version>/token

Use an HTTP Basic Authentication header to provide your client key and client secret to the access token URL.

To prepare your credentials for the POST request, concatenate the client key with the client secret, separated by a colon, in the form:

Your application must POST the token request to the access token URL with the Content-Type application/x-www-form-urlencoded, and with the grant_type value authorization_code plus the authorization code and redirect URI. That is, grant_type=authorization_code&code=<authCode>&redirect_uri=<redirectURI> is the body of the request.

The following is a complete access token request using the example credentials:

POST /iii/sierra-api/token
Host: example-library.edu
Authorization: Basic RWx2aXM6UHJlc2xleTE=
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=1d4437d46b0ea2cfd7d1d16fa42b8f0a
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

Access Token Response

The system returns an access token in response to a request with valid credentials. For example:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"gbKjvov2k8PW_LqZerTYyq_i7v8kkfTGwwZX6jux19_WCW8lqeWyf6ReRQu5jKTE",
  "token_type":"bearer",
  "expires_in":3600
}

The response includes the token's lifetime in seconds.

You can extract the access_token and token_type values from the response for use in the authorization header of API calls.

Errors

The system returns an HTTP 401 (Unauthorized) error and a WWW-Authenticate challenge if your token request includes invalid or missing credentials:

WWW-Authenticate: Basic realm="sierra-api"

The system returns an HTTP 400 (Bad Request) error if your token request is malformed.

Sending an Access Token with an API Request

All API requests must include the following HTTP authorization header:

Authorization: Bearer <access token>

The access_token is the token from the access token response. Note that the authorization scheme is Bearer, not Basic.

The following is an example API request:

GET iii/sierra-api/v6/patron/2666444
Host: example-library.edu
Authorization: Bearer gbKjvov2k8PW_LqZerTYyq_i7v8kkfTGwwZX6jux19_WCW8lqeWyf6ReRQu5jKTE
Content-Type: application/json;charset=UTF-8
User-Agent: MyAppName
X-Forwarded-For: <Client IP Address>

Errors

The system returns an HTTP 401 (Unauthorized) error, a WWW-Authenticate challenge, and invalid_token if your request includes invalid, expired, or missing credentials:

WWW-Authenticate: Bearer realm="sierra-api"