Using API credentials
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.
Updated 7 months ago