Using OAuth 2.0 to access Cloudinary APIs

Cloudinary supports the OAuth 2.0 protocol to authenticate and authorize access to its APIs. This can be useful for implementing integrations between another application or platform and Cloudinary.

Overview of the OAuth 2.0 flow

There are different OAuth 2.0 flows corresponding to different grant types, but in general, when a Cloudinary user wants to access their resources through an application, using OAuth 2.0, the following steps are involved:

1. The application makes an authorization request to Cloudinary, on the user's behalf.
2. Cloudinary returns an authorization page for the user to grant access to their Cloudinary account.
3. The user's credentials and authorization are returned to Cloudinary's authorization server.
4. Cloudinary's authorization server issues an access token and refresh token to the application (this step may involve a redirect to a specified URI in order to handle the callback).
5. The application uses the access token when making calls to Cloudinary's APIs, to authorize access to the user's resources.

Setup

To use OAuth 2.0, you need to obtain client-specific credentials from Cloudinary.

Submit a request to Cloudinary Support with the following details:

• The name of the product that you want to integrate with Cloudinary
• Your company name
• A contact name
• A contact email address
• A short explanation about the integration
• A list of redirection URIs to be used during the OAuth 2.0 flow

Cloudinary will give you a client ID and key.

Requesting an access token from Cloudinary

It is recommended to use an OAuth 2.0 library to implement the OAuth 2.0 protocol in your application.

Your application should:

• Provide a means to log into Cloudinary that initiates the OAuth 2.0 flow using one of the defined grant types.
• Use your client ID and key to request a cloud-specific access token from the Cloudinary Authorization Server (https://oauth.cloudinary.com/oauth2/auth). Depending on the grant type, an authorization code may first be issued that the application needs to exchange for an access token through the token endpoint (https://oauth.cloudinary.com/oauth2/token).
• Maintain the access token to use in API calls.

Using an access token to make API calls

Your application should send the access token in an HTTP Authorization request header for every request to a Cloudinary API endpoint.

For example, requesting all images from the product environment with cloud name demo, given an access token of MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI4:

Using an access token in SDK API calls

If you're using one of the Cloudinary SDKs to make API calls, then you can use an access token instead of using your API key and API secret for authentication. Assign the access token to the oauth_token parameter.

You can set oauth_token in your configuration parameters, or in some SDKs, you can pass oauth_token as an optional parameter to API calls.

Example 1

Set oauth_token in your configuration parameters, then make API calls as normal:

Example 2

Pass oauth_token to an Upload API method (without setting oauth_token in configuration parameters):

Example 3

Pass oauth_token to an Admin API method (without setting oauth_token in configuration parameters):

Refreshing an access token

Access tokens have a limited lifetime. Your application can request an access token to be re-issued when its lifetime expires. A refresh token, which is issued at the same time as the access token, is used to make this request as described in Refreshing an Access Token.

The expiry times of the tokens are as follows:

Querying an access token

The Admin API contains an endpoint that you can call to discover the cloud name for a particular access token.

Syntax

GET https://api.cloudinary.com/v1_1/token/info

Include the access token in the HTTP Authorization request header.

Example

Request the cloud name for the access token MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI4:

Sample response

Revoking OAuth 2.0 access

To revoke an application's OAuth 2.0 access to the Cloudinary APIs, contact Cloudinary Support.