Patron Authentication

OverDrive's Circulation APIs are secured behind our Patron authentication. We use OAuth 2.0, which provides developer account authentication and verification by way of an access token.

Once your developer application for Patron authentication has been approved, OverDrive will provide a client key and client secret which, when provided to the OverDrive authorization endpoint, will return an access token.  The access token must be included with each Circulation API request. If you haven't already, take a look at the Getting Started page to learn how to register for your credentials.

Patron authentication grants you access to both Circulation and Discovery APIs.

Note: All patron authentication POSTs use the same URL (https://oauth-patron.overdrive.com/patrontoken) in both the production and integration environments.

When using Patron authentication, all Circulation API web requests from client apps must be authorized using the OAuth 2.0 "Resource Owner Password Credentials Grant."  This type of OAuth flow is very similar to the "Client Credentials Grant" that OverDrive's Discovery APIs use extensively. The two differences are:

1. In addition to OverDrive-issued OAuth credentials, client apps must also submit the patron’s library card number as the “username” POST parameter and the patron’s PIN as the “password” POST parameter with the OAuth 2.0 token request.
2. The OAuth “scope” POST parameter must be submitted with the access token request.  Client apps should submit an OAuth "scope" containing an OverDrive "Website ID" and "ILS Name."

OAuth 2.0 "token" endpoint for Patron authentication

Circulation API web requests must first obtain an OAuth 2 access token on behalf of the patron from the following patrontoken endpoint:

https://oauth-patron.overdrive.com/patrontoken

Requests to this endpoint must occur under SSL.

Using OAuth Tokens for Patron authentication

To create the POST request for an Patron's OAuth access token:

• Combine your client key and client secret like this:  clientKey:clientSecret.
  Note: Both the clientKey and clientSecret are case sensitive.
• Use your language's libraries to encode the combined secret and key using a Base64 algorithm.
• Apply the string to the Authorization header like this:  Basic {Base64-encoded string}
• The form-encoded Request Body should be formatted like this:
  grant_type=password&username={library card number}&password={PIN}&scope=websiteid:{websiteid} authorizationname:{authorizationname}

POST /patrontoken HTTP/1.1
Host: oauth-patron.overdrive.com
Authorization: Basic {Base64-encoded string}
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=password&username=1234567890&password=1234&scope=websiteid:12345 authorizationname:default

If the target digital collection does not 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.  See the example below:

POST /patrontoken HTTP/1.1
Host: oauth-patron.overdrive.com
Authorization: Basic {Base64-encoded string}
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=password&username=1234567890&password=[ignore]&password_required=false&scope=websiteid:12345 authorizationname:default

Note: You cannot bypass the PIN requirement of a given collection by setting password_required=false. If a PIN is required, then it must always be passed to successfully authenticate.

The scope POST parameters are:

• websiteid:{websiteid} (required) - Indicates the OverDrive website ID that is being requested. To get a website ID, request one through our support form.
• The authorizationname:{authorizationname} (required) - Indicates the OverDrive ILS name that is being requested. To get the authorization name, request one through our support form.

Note: The OAuth 2.0 spec states that the scope POST parameters should be expressed as a list of space-delimited strings.

 If your credentials are valid, an access token will be returned in the POST response:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Date: Wed, 31 Jul 2013 13:46:45 GMT
Content-Length: 588

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"Bearer",
    "expires_in":3600,
    "scope":"LIB META SRCH AVAIL patron website:12345 authorizationname:default"
}

You should extract the access_token and token_type values from this response to include in Circulation API requests as part of the Authorization header as shown in the example below:

GET /v1/patrons/me HTTP/1.1
Host: api.overdrive.com
Authorization: Bearer {OAuth patron access token} 
User-Agent: {Your application}

You'll need to present the patron's OAuth access token when making a request to any OverDrive Circulation API when using the Patron authentication workflow.  Each patron's OAuth access token expires after one hour (the expires_in value is 3600 seconds).  If you send a token and receive a 401 'Unauthorized' error in response, then your token has expired and you'll need to request a new one.

When integrating with OverDrive APIs, it's recommended that you use an OAuth 2.0 Client Library specific to the programming language that you're using.