Client Credentials Grant

Use the Client Credentials Grant flow when your application requires global data access. A user access token provides developer account authentication and authorization.

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 access to its system.
   2. Create a client secret. The client secret must be at least 8 characters long.
2. Your client application uses the key/secret pair to request an access token from the Sierra REST API authorization endpoint.
3. 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 and Using OAuth Tokens

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 client_credentials. That is, grant_type=client_credentials is the body of the request.

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

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

grant_type=client_credentials

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 to 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/bibs/1000004
Host: example-library.edu
Authorization: Bearer gbKjvov2k8PW_LqZerTYyq_i7v8kkfTGwwZX6jux19_WCW8lqeWyf6ReRQu5jKTE
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"