Contentstack OAuth

Contentstack OAuth is an OAuth 2.0 protocol that allows external applications and services to access Contentstack APIs on behalf of a user. OAuth 2.0 can be maintained with apps in the Developer Hub console.

When to use Contentstack OAuth

Contentstack OAuth enables external applications to gain restricted access to a user's data. This approach separates authentication from authorization allowing the implementation of various methods that utilize different device capabilities.

1. When you want an external application to authenticate a user or an application without sharing user credentials.
2. When you want an external application to authenticate a user or an application without sharing the management token.
3. When you want an external application to only gain access to a subset of APIs and not the entire collection of APIs.
4. When you want an application to be transparent about the key it requests and for what the application will use it.

Types of Contentstack OAuth Tokens

There are two types of OAuth tokens that you will need to access your applications:

• App Config Tokens
• User Config Tokens

App Config Token

App Config Tokens are associated with installed applications. Their scopes can be different from user token access. You can use the app config token only when you install an application.

Note: The app config token is revoked if the application is uninstalled.

This token does not create a user-level audit trail. It should mainly be used for server-to-server and long-lived communications.

User Config Token

The User Config Token is associated with the users who authorized it. Their scopes can be different from app token access. This token can be used for an hour and then be refreshed using the refresh token.

Note: The user config token is revoked after a scheduled timeout.

This token creates a user-level audit trail of the user that authorizes the token. It should mainly be used for server-to-server and long-lived communications.

Integrate your Apps with Contentstack OAuth

You can create custom applications in Developer Hub. It provides the necessary tools to develop an app. While developing apps, you can integrate your application with the Contentstack OAuth.

To integrate your app with Contentstack OAuth, log in to your Contentstack account and follow the steps below:

1. On the left navigation panel, you will find a new icon for Developer Hub (as shown below). Click on the icon to go to the Developer Hub.
   
2. Click on the + New App button.
3. In the resulting New App modal, enter the following details:
   1. Name: Enter the app's name (for example, Sample App).
   2. Description (optional): Enter a description for your app.
4. Click on the Create button.
5. On the Basic Information screen, you can view general details about your app, such as name, description, and app UID.
6. You can add an icon for your app by clicking on the Upload a new file button.
7. Click on the Save button.

Configuring Contentstack OAuth

Configuring OAuth and its scopes allows your app to perform tasks in your development workspace. You can configure and select scopes through the OAuth option available in your app.

To configure OAuth, log in to your Contentstack account and follow the steps below:

1. Create a new App or Click on the app you want to configure.
   
2. On the left navigation panel, click on the OAuth tab.
   
3. In the OAuth Details page, the following options are displayed for your app:
1. Client ID: The Client ID identifies your application and frequently appears in the OAuth negotiation URLs. You can freely share client IDs in code and emails, but you cannot use them alone to perform actions on behalf of your app.
2. Client Secret: The Client Secret identifies your application's rights when exchanging tokens with Contentstack. You cannot share the client secret keys via emails, distributed native applications, client-side javascript, or public code repositories.
3. Redirect URL (optional): Contentstack will redirect users to the callback URL configured in your app's settings if the redirect URL is not present.
4. Add the relevant app or user token scopes.
5. Click on Save to save your OAuth configurations.

Note: User permission scopes can be passed dynamically in the Authorization URL while authorizing a user.

Next, you can check out how to add the App and User Token Scopes.

Add App Token Scopes

In the OAuth page, you will find the App Token section that lets you add app-related permission scopes. To do so, perform the following steps:

1. Click on + App Scopes.
2. From the resulting Select App Token Scopes pop-up window, select the permission you want to set up for your application.
   
3. Once done, click on Choose Scope(s).

Add User Token Scopes

In the OAuth page, you will find the User Token section that lets you add user-related permission scopes. To do so, perform the following steps:

1. Click on the + User Scopes button.
2. From the resulting Select User Token Scopes pop-up window, select the permissions you want to set up for your users.



3. Once done, click on Choose Scope(s).

Additional Resource: Learn more about the app and user token scopes from the OAuth Scopes document.

Authorizing OAuth Apps

To authorize users for your application, follow the steps given below:

1. In your application, request user identification for relevant regions.
2. The authorization page shows what permissions the app is requesting.
3. A Contentstack user may authorize or deny an application based on the permission scope.
4. The user is then redirected back to the redirect URL configured by the developer with the authorization code.
5. When the user authorizes the request, developers exchange the authorization code with the access token by calling the token API endpoint.
6. With the user access token, the app can now access the Contentstack API.
7. Tokens expire after a specific period of time, and they can be renewed using the new token sent in the token API response.

Request user identity

Once you install your app, the authorization page appears that contains the authorization URL. Through this page, you request access and permission scopes.

Your authorization URL or AuthURL might look like this for app requesting authorization in NA region:

https://app.contentstack.com/#!/apps/{app_uid}/authorize?response_type=code&client_id={[…]d}&redirect_uri={redirect_uri}&scope={scope}&state={state}

The following parameters describe the AuthURL:

• Base URL: The base URL of Contentstack where your app is installed. This will be different for each Region. Please use the relevant one where the user organization is located.
• [Required] client_id: The app’s client ID.
• [Required] response_type: The type of data contained in the response.
• [Optional] redirect_uri: The redirect URL where Contentstack will send the user.
• [Optional] scope: The permission scopes set for your application. Refer to the OAuth Scopes document for a list of all the permission scopes for Contentstack OAuth.
• [Optional] state: This parameter is used to achieve per-request customization.

Note: You can find the App UID in the basic information section of the app. All query parameters should be URL-encoded.

Authorizing your App

A pop-up window displays all the permission scopes associated with your application.

1. Click on the Authorize button to give permissions to the user.
2. The user is redirected to Contentstack for identification, and they can see the permissions requested by the application.
3. The user must choose the organization to which the application should share access.
4. Tokens shared with the application are scoped to an organization.

   Note: You will receive a separate token for each organization's authorization.

5. The user can then either Authorize or Deny it.

Users are redirected to website by Contentstack

When users grant permission for their app to access the Contentstack organization, they'll be redirected to the website configured in the Contentstack app with a temporary authorization code.

An example of the redirect URL with authorization code and location:

https://example.com/oauth/callback?code={authorization_code}&location=NA

Exchange authorization code for access token

You need to exchange the authorization code for an access token using the Token API.

You can use the following request code to fetch the access token:

POST {BASE_URL}/apps/token
Headers: 
  Content-Type: application/x-www-form-urlencoded
Request Body:
  grant_type:authorization_code
  client_id:{client_id}
  client_secret:{client_secret}
  redirect_uri:{redirect_uri}
  code:{authorization_code}

Your output will look as follows:

{
    "access_token": "310e426d3d0b2de46c4e3761c56af68a",
    "refresh_token": "74ac59bf120b1ac47f4ec715e4c8db17",
    "token_type": "Bearer",
    "expires_in": 3600
}

Refresh Token

The OAuth flow begins with a user interacting with your app and ends with your app authorized to access Contentstack resources in a way dictated by the user. The access token allows you to access the app's data.

With a regular expiration for your access token, the danger of the token falling into the wrong hands is reduced. But to maintain control over app data, your app needs a way to request a new access token regularly.

A refresh token allows your app to rotate its access tokens seamlessly, using the same token endpoint to acquire access tokens with the refresh token.
You need to pass the refresh token in the code parameter.

Use access token with Contentstack APIs

Your access token allows you to call the methods described by the permission scopes you set during authorization. For example, the user:write scope allows your app to post messages.

Multiple Region Support

Since Contentstack is hosted at multiple data centers, the API domain URL varies for each data center. Learn more about Contentstack Regions.

Private apps only authorize specific organization members in which the app is developed. Suppose you want your application to execute OAuth capabilities across all regions/data centers. In that case, you need to publish your app either as a Public App or a Public Unlisted App.

Additional Resource: Learn more about app visibility status.

Here, the developers need to identify which data center the client has authorized the app from and the region the organization is hosted. After authorization, developers can identify the region using the location parameter in the redirected URL.

The regional parameters are as follows:

This is required as all Contentstack API’s are scoped to the region.