Migrating from basic authentication to OAuth 2.0 credentials

Get ready for our new authentication system


Basic Authentication will be deprecated on June 15, 2023, in favor of OAuth 2.0.

We're sunsetting support for basic authentication from June 15, 2023. We recommend you follow the steps described on this page to keep your application running.

This page describes how you can migrate a live API account from Basic authentication to OAuth 2.0. You can also watch the following video walkthrough of the process.

Compared to Basic Authentication

Traditional Basic authentication (i.e. using a username and password) requires a complete set of credentials to be passed to our API with each call.

When using OAuth 2.0 with this particular credentials flow, access to your Ocrolus resources can be controlled more tightly; your code needs to only authenticate occasionally.

Think of the client credentials flow as a seasonal pass for a sports team, delivered as a book of printed tickets for individual games. You can leave your seasonal ticket (i.e. your client credentials) at home while bringing only a day ticket (i.e. a token) for a particular game.

Once the game starts (i.e. when the token's time limit expires), the day ticket is rendered invalid even if it was never used. If you carry around the day ticket, someone can steal it from you and try to use it. However, the rest of your ticket book is safe. You can report your day ticket as stolen (i.e. revoke the compromised token), pull out a new ticket from the seasonal pass (i.e. generate a new token), and try again.

Before you get started

Ocrolus API basic authentication credentials (e.g. an email address and password) are provisioned to separate user accounts. Any documents or data uploaded through one API account are only accessible to that API account. In order to properly transition your account from basic authentication credentials to OAuth 2.0 credentials, you need to follow the API Credential migration tool in the API Credentials tab of the Settings Center.

To get started, click "Migrate" next to the appropriate basic auth "Legacy API Credentials."


A list of legacy Basic authentication credentials. One active set of credentials is displayed. The Migrate option is clickable. The Remove Credentials option is not yet clickable, as the migration process has not been started. The associated e-mail address is blurred because it's in active use.

Once you have selected a particular account to migrate, the migration tool will assist you in creating OAuth 2.0 credentials for your API account.


Once the OAuth 2.0 credentials have been created for your API account, test them by requesting a JWT access key. Once your production application has migrated over to the new OAuth 2.0 credentials, and you've confirmed that it is working, you may delete the old credentials by clicking "Remove Credentials" under the Legacy API Credentials table.

curl --request GET \
    --url https://api.ocrolus.com/v1/books \
    --header 'authorization: Bearer ACCESS_TOKEN'