Was this article helpful?
Thanks for your feedback
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.
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.
There are two types of OAuth tokens that you will need to access your applications:
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.
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.
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:
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:
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.
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:
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:
Additional Resource: Learn more about the app and user token scopes from the OAuth Scopes document.
To authorize users for your application, follow the steps given below:
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:
Note: You can find the App UID in the basic information section of the app. All query parameters should be URL-encoded.
A pop-up window displays all the permission scopes associated with your application.
Note: You will receive a separate token for each organization's authorization.
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
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 }
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.
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.
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:
Region | Parameter |
North American | NA |
Europe | EU |
Azure North American | Azure_NA |
This is required as all Contentstack API’s are scoped to the region.
Was this article helpful?
Thanks for your feedback