Overview

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

Using OAuth 2.0 Client Libraries

In order to use OAuth 2.0, we strongly recommend you use dedicated client libraries. You can find links to popular OAuth 2.0 client libraries below.

Note: These libraries are written and maintained by third parties, so Ocrolus isn't responsible for any change in them.

Requesting a Token

We use JSON Web Tokens (JWTs) as defined by RFC 7519. In order to request a Token, you should 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.