QR code authentication

As an alternative to patron authentication, you can authenticate users with your product via a QR code flow. This flow doesn't require you to have access to users' library, school, or corporate credentials.

To use the QR code flow:

1. Direct users to the OverDrive QR code page.
2. From there, users can scan a QR code, or use a link alternative if they can't scan the code, and sign into OverDrive services.
3. After authenticating, users are redirected to a URL (set by you) with an auth code.
4. Exchange the auth code for the user's access token.

Directing users to the QR code page

To direct users to the OverDrive QR code page, send a GET request to this URL:

Query parameters

Your GET request must include the following URL-encoded parameters:

This request redirects the user to an OverDrive page with a QR code that they can scan with a mobile phone or tablet. If they can't scan the QR code, the page provides a URL and 8-letter code that the user can enter manually in a web browser.

Once the user selects a sign-in method, they'll be prompted to select their library (if needed); sign in with their library, school, or corporate credentials; and approve access for your API client.

Completing user authentication

When the user successfully signs into their library or school, they'll be sent to the redirect_url provided in your GET request. The redirect_url will have a 64-character auth code appended as a query parameter, which you can exchange for an access token.

To get the 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 properties to the request body:
   • grant_type=authorization_code.
   • code: The 64-character authentication code appended to the redirect_url.
5. Format the form-encoded request body like this:
   grant_type=authorization_code&code={auth code}

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: Use the Circulation APIs (Patron Information, Checkouts, Holds) with patron auth or QR code auth in the production environment.
  • PATRONINT: Use the Circulation APIs with patron auth or QR code auth in the integration environment.
  • DEVICELOGIN: Use the Circulation APIs with QR code auth in the production environment.
  • DEVICELOGININT: Use the Circulation APIs with QR code auth in the integration environment.
    Note: You’ll also have access to the Magazine Issues API and Digital Inventory API, which won’t appear as scopes.
• A refresh_token that you can use to refresh the user's access token for up to 30 days.

Refreshing a user's access token

To refresh a user's access token, send a POST request to this URL:

The request should be formatted similarly to your POST request to the code endpoint, but the properties in the request body should be:

• grant_type=refresh_token.
• refresh_token: Use the refresh token returned in the POST response from the code endpoint.

A successful response will return the same information as the response from the code endpoint, including a new refresh_token that you can use in your next POST request to the refresh endpoint.