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

OAuth 2.0 client libraries help you simplify secure authentication, provide fine-grained access control, and follow a standardized and well-supported protocol. To use OAuth 2.0, we strongly recommend using dedicated client libraries. Below are links to popular OAuth 2.0 client libraries:

• Python
• Java
• Node.js
• Other Languages

📘

Note

These libraries are developed and maintained by third parties. Ocrolus is not responsible for any modifications or updates made to them.

Requesting a token

We use JSON Web Tokens (JWTs) as specified by RFC 7519. To request a token, use the Grant Authentication Token endpoint. The token will be returned in the access_token field of the response.

{
  "access_token": "eyJz93a...k4laUWw",
  "token_type": "Bearer",
  "expires_in": 86400
}

Using a token

Every API endpoint accepts your access token through the HTTP Authorization header. The token should be included in the header formatted as `Authorization: Bearer <your access token>`.

The specific way you provide your token can vary depending on the client tool or library you use. The below example uses cURL to send an access token. To send the access token using cURL, perform the following steps:

1. Prepare your access token. The token is a long string that was provided to you when you authenticated.

   cURL

   Authorization: Bearer <your access token>
   

2. 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. The --oauth2-bearer option automatically configures the header for you, you only need to provide the access token. The complete token comes from the access_token field in the Grant Authentication Token endpoint's response.

   cURL

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

Token expiration

Newly generated tokens are valid for the duration specified in the response from the Grant Authentication Token endpoint. Currently, all tokens expire after 24 hours (86,400 seconds). However, we recommend refreshing tokens every 12 hours (43,200 seconds) to ensure continuous access.

🚧

What if the credential is revoked?

Revoked credentials cannot be used to create new access tokens. Additionally, if a credential is revoked, then any existing tokens associated with it may expire earlier than their stated expiration time. Therefore, do not rely on tokens issued from revoked credentials, as they may become invalid unexpectedly.