OverDrive Developers

Granted authorization

Tags: Authentication

Granted authorization, also known as "Authorization Code Grant" or "3-Legged Authorization," allows you to give users access to OverDrive digital collections without needing to know their library credentials. Users will authorize your app or web service to log in on their behalf, just like they would authorize their Facebook or Google accounts to log them into other services.

With this authorization type, you'll be able to use all of our Circulation and Discovery APIs.

To get started, use this URL:

https://oauth.overdrive.com/auth?client_id={ID}&redirect_uri={URLredirectedTo}&scope=accountId:{ID}&response_type=code&state={optionalStateParameter}

Here's what each parameter means:

ParametersExplanations
client_id
Required
Your API client key.
redirect_uri
Required
Your users will be redirected to this URI after authentication. Please make sure this field matches the URI you provided here.
accountId
Required
The collection account ID (you can find this in the Member Center).
state *
Optional
This is a variable you can create for security. Pass something here, and we'll pass it back to you, so that you know your API request wasn't intercepted and altered.

*Note: The state parameter is also a good way to keep track of who you're authenticating.

After navigating to the URL above with the required variables, your users will be sent to their digital collection’s login and approval page via 302 redirects.

Once users approve your service for login to their library, you’ll get a response that sends them back to your redirect URI.

Note: Each time users access a digital collection through EZProxy or Federated Authentication, they must select Allow Once when approving your service. EZProxy and Federated Authentication do not support the refresh token required for Allow Always.

Here’s what the response looks like:

HTTP/1.1 302 Found
Cache-Control: private, s-maxage=0
Content-Type: text/html; charset=utf-8
Location: {where you wanted to be redirected}

{redirectUri}?code={authorizationCode}[&state={optionalStateParameter}]

Note the {authorizationCode} and {optionalStateParameter}. The authorization code is needed for your POST request, and the state parameter should match the one you originally passed.

Then, get an access token

Create a POST request:

  • 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} (see the example below).
  • Include a valid {authorizationCode} and {redirectUri} in the body of the request.

Here's a template for how your request will look:

POST /token HTTP/1.1
Authorization: Basic {Base64-encoded string}
User-Agent: {Your application}
Content-Type: application/x-www-form-urlencoded
Host: oauth.overdrive.com

grant_type=authorization_code&code={authorizationCode}&redirect_uri={redirectUri}

A successful response looks like this:

HTTP/1.1 200 OK
Cache-Control: no-store, must-revalidate, no-cache, max-age=0
Pragma: no-cache
Content-Length: 1095
Content-Type: application/json; charset=utf-8

{
    "access_token":"gAAAAB44Au1K7B2dvZzcIacUqHbihx3M...",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"RdNP!IAAAAJ6Kh9c-bjy-0y3DOYlSaP...",
    "scope":"LIB META AVAIL SRCH PATRON websiteid:{int} puid:{int}"
}

You can now use this access token to use all OverDrive APIs, Discovery and Circulation.

If your user opts to "Always allow" you to authenticate them via their OverDrive library website, you can use the provided refresh token to quickly refresh that user's authentication.

To use a refresh token, your authorization call must look like this:

POST /token HTTP/1.1
Authorization: Basic {Base64-encoded string}
User-Agent: {Your application}
Content-Type: application/x-www-form-urlencoded
Host: oauth.overdrive.com

grant_type=refresh_token&refresh_token={refresh_token}