❗️

Attention

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 specific credentials flow, access to your Ocrolus resources can be more granularly controlled, requiring your code to authenticate only occasionally.

Think of the OAuth 2.0 Client Credentials Flow as a secure access system for your application. Your client credentials are like a master key that you keep in secure storage. When your application needs to access resources, it requests a temporary access token from the OAuth server using its client credentials. This access token is like a single-use key that grants access for a limited time.

Once the access period ends and the token expires, the access token is no longer valid even if it was never used. If the access token is compromised or stolen, it can be used by an unauthorized party. However, your client credentials remain secure. You can report the compromised access token, revoke it, and request a new access token using your client credentials, ensuring continued secure access.

Prerequisite

Ocrolus API Basic Authentication credentials are provisioned to separate user accounts. Any documents or data uploaded through one API account are only accessible to that API account only. 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.

Migration procedure

To migrate from the Basic Authentication to OAuth 2.0, perform the following steps:

1. Log in to the Ocrolus Dashboard.

2. Click on the Account & Settings icon at your screen's top right corner and select API Credentials from the dropdown list. The API Credentials page appears.

   

3. Under Legacy API Credentials, you will find all your Basic Authentication credentials. Click Migrate for the credential you want to migrate.

   

4. Once you have selected a particular account to migrate, the migration tool will generate the Client ID and Client secret ID. Follow the on-screen instructions and click on the ADD CREDENTIALS.

   

5. After you create the OAuth 2.0 credentials for your API account, test them by requesting a JWT access key. Once you have migrated your production application to the new OAuth 2.0 credentials and confirmed it is working, you can delete the old credentials by clicking Remove under the Legacy API Credentials table.

   
   
   cURL

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