[BETA] Using API Credentials

🚧

This is in beta!

This page describes functionality that is in beta, and is therefore subject to change. We would greatly appreciate it if you reported any feedback (including bugs) to customer service. The same goes for this documentation.

Overview

Once you create a credential as described here, you're ready to start using our API. This page explains how you can use your new credentials to do that.

About Access Tokens

We use JSON Web Tokens (JWTs) as defined by RFC 7519.

Requesting a Token

Use the Grant Authentication Token endpoint. It is returned in the response's access_token field.

Using a Token

Every API endpoint accepts your access token through the HTTP Authorization header. It should have a value of Authorization: Bearer <your access token>.

The exact mechanism by which you provide your token depends on your choice of client tool or library, but here's an example of how you can do so with curl:

curl --url "https://api.ocrolus.com/v1/books" --oauth2-bearer "eyJhbGciOiJ...2hUye_4CpIvQ"

The --oauth2-bearer option configures the header for you; you just need to provide the access token.

The (abbreviated, for our purposes) token of eyJhbGciOiJ...2hUye_4CpIvQ comes from the access_token field in the Grant Authentication Token endpoint's response.

Token Expiration

Newly-generated tokens are valid for as long as is given in the Grant Authentication Token endpoint's response. All tokens currently expire after 24 hours (86,400 seconds), but we suggest refreshing tokens every 12 hours (43,200 seconds).

🚧

What if the credential is revoked?

Revoked credentials cannot be used to create new access tokens. However, if a credential is revoked then any outstanding tokens may expire before their stated time is up. Please don't rely on them.

Simplifying Token Management

The OAuth 2.0 protocol sits atop standard HTTP and JSON conventions, therefore you may use any general-purpose HTTP library you'd like. However, OAuth's use of time-limited tokens means that your application frequently needs to retrieve, cache, and renew tokens. We suggest using a dedicated OAuth 2.0 client library that handles most of these steps for you.

You can find links to OAuth 2.0 client libraries for a variety of popular technologies (including Python, Java, and Node.js) on their official website here. Note that these libraries are written and maintained by third parties, so we can't endorse any one of them in particular.


Did this page help you?