Patron authentication

You'll use patron authentication to access the Circulation APIs and the Discovery APIs when users are signed into your product.

Once you've been approved for API access, OverDrive will provide a client key and client secret, which you can use to get an access token. Learn about requesting API credentials.

Authorizing client apps with patron authentication

When using patron authentication, all web requests from client apps must be authorized using the OAuth 2.0 "Resource Owner Password Credentials Grant." This type of OAuth flow is similar to the "Client Credentials Grant" that's used for client authentication. The two differences are:

• In addition to OverDrive-issued OAuth credentials, client apps must include the user's ID (often a library card number or student ID) and password (or sometimes a PIN) in the POST parameter with the OAuth 2.0 token request.
• Client apps should submit an OAuth "scope" with the access token request containing an OverDrive website ID (i.e., a digital collection) and authorization name.

Using OAuth tokens for patron authentication

To get a patron access token, send a POST request to this URL:

In the POST request:

1. Combine your client key and client secret like this: clientKey:clientSecret.
   Note: Both the clientKey and clientSecret are case sensitive.
2. Use your language's libraries to encode the combined secret and key using a Base64 algorithm.
3. Apply the string to the Authorization header like this:  Basic {Base64-encoded string}
4. Add the required scopes to the request body:
   • websiteid: The digital collection that's being used with the user's credentials.
   • authorizationname (or ilsname): The ILS name for the digital collection.
     Tip: If you need either parameter, you can request them through our support form.
5. Format the form-encoded request body like this:
   grant_type=password&username={user ID}&password={PIN}&scope=websiteid:{websiteid} authorizationname:{authorizationname}
   Tip: The OAuth 2.0 spec states that the scope POST parameters should be expressed as a list of space-delimited strings.

If the specified website ID (i.e., digital collection) doesn't require a PIN/password, then an additional parameter must be added to the request body: password_required=false. Since the OAuth 2.0 "Resource Owner Password Credentials Grant" specifies that the user's password is always required, your client app must also provide a non-empty value for the password parameter (like "nopin" or "ignore").

In the response, you'll get:

• The token_type and access_token, which you'll need for future Circulation and Discovery API calls in the Authorization header. For example:

  GET /v1/patrons/me HTTP/1.1
  Host: api.overdrive.com
  Authorization: {token_type} {access_token}
  User-Agent: {Your application}

• When the token expires (expires_in), which is 3600 seconds (or one hour). Once expired, you'll need to request a new token or your API calls will return a 401 error.
• The scopes, which tell you which APIs you have access to:
  • LIB: Library Account API
  • META: Metadata API
  • SRCH: Search API
  • AVAIL: Library Availability API
  • PATRON: The Circulation APIs (Patron Information, Checkouts, Holds) in the production environment
  • PATRONINT: The Circulation APIs in the integration environment