Discovery API "Client" Authentication

Tags: Authentication-projection

OverDrive's Discovery APIs are secured using OAuth 2.0, which provides developer account authentication and verification by way of a user access token. Once your developer application 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 API request. If you haven't already, take a look at the Getting Started page to learn how to register for your credentials.

Client authentication grants you access to Discovery APIs.

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

Learn more about the OAuth protocol.

Using OAuth Tokens

All of OverDrive's Discovery APIs use the OAuth 2.0 "Client Credentials Grant" to authenticate your client credentials. You can get an OAuth access token at https://oauth.overdrive.com/token by providing your client key and client secret using Basic Authentication.

To create the POST request:

Combine your client key and client secret like this: clientKey:clientSecret.
Use your languages libraries to encode the combined secret and key using a Base64 algorithm.
Apply the string to the Authorization header like this: Basic [Base64 string] (see the example below).

POST /token HTTP/1.1
Host: oauth.overdrive.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=client_credentials

If your credentials are valid, an access token will be returned as part of the response:

200 OK
Pragma: no-cache
X-Frame-Options: deny
Content-Length: 1022
Cache-Control: no-store, must-revalidate, no-cache, max-age=0
Content-Type: application/json; charset=utf-8
Date: Wed, 24 Feb 2016 14:00:44 GMT

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"Bearer",
    "expires_in":3600,
    "scope":"LIB META SRCH AVAIL"
}

Your client application should extract the access_token and token_type values from this response and include them in any subsequent OverDrive Discovery API calls as part of the Authorization header as shown in the example below:

GET /v1/libraries/1225 HTTP/1.1
Host: api.overdrive.com
Authorization: Bearer {OAuth access token}
User-Agent: {Your application}
X-Forwarded-For: (Client IP Address)

You'll need to present this OAuth access token when making a request to any OverDrive Circulation API. Each 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 is recommended that you use an OAuth 2.0 Client Library specific to the programming language that you are using.