Tokens

Tokens are needed to authorize API calls.

Contentstack provides Content Delivery and Content Management APIs to manage the content of your Contentstack account. The Content Delivery API is used to retrieve content from your Contentstack account, while the Content Management API is used to manage the content of your Contentstack account.

To make authorized Content Management API requests, you need to use the stack API Key along with either an authtoken or a Management Token.

• For API Key and Authtoken-based authentication:
  • Pass the stack’s API key against the api_key parameter as header
  • Pass the user Authtoken against the authtoken parameter as header

• For API Key and Management Token-based authentication:
  • Pass the stack’s API key against the api_key parameter as header
  • Pass the user Management Token value against the authorization parameter as header

For Content Delivery APIs, you need to authenticate your request with a Delivery Token that has been assigned to a specific publishing environment.

Let us take a look at these tokens in detail.

Management Tokens

Management Tokens provide read-write access to the content of your stack. It is a credential—used along with the stack API key—to make authorized Content Management API (CMA) requests for managing content of your stack.

Key Features

Let’s look at the key features of Management Token:

Stack-level token; not a user-specific token
An important thing to know about Management Token is that it is not a user-specific token. It’ a stack-level token, and can be used to make authorized CMA by anyone who has access to it.

Provides access control
While creating management tokens, you can define if this token can be used to perform just READ activities, or both READ and WRITE.

Provision to set expiry
You can define if the token should have a specific expiry (i.e., expire on a specific date) or not expire at all.

Owner/admins can create
Only the stack owner or admins can create a management token.

Limitations
Maximum 10 active management tokens can be live in a stack. Management tokens cannot be used to invite or remove users or add approval-related publish rules. Read more about its limitations.

Capabilities of Management Tokens

A management token with READ & WRITE permissions can perform all actions on the following modules:

• Entries
• Assets
• Content types
• Labels
• Extensions
• Releases
• Environment
• Languages
• Webhooks
• Roles
• Users (Except adding and removing users to/from a stack)
• Workflows
• Publish Rules (Except set up publishing rules that require approval of users or roles)
• Audit Log (Read-only)
• Publish Queue

A management token with just READ permissions can be used to make all GET requests for the modules mentioned above.

Note: Management tokens cannot be used for the following modules: organization, stack, user session, and tokens.

Why Management Tokens

Useful for SSO users
Since the users of SSO-enabled organizations login via an identity provider (IdP), they don’t get an Authtoken to make authorized CMA requests. A workaround is to disable SSO Strict Mode, and login using traditional Contentstack login mechanism. Management Token solves this problem. SSO users can now use Management Tokens to make authorized CMA requests, without logging in through traditional method.

Run scripts and integrations without using personal tokens
Since management tokens can perform almost all the actions that an Authtoken can do (there are some exceptions though), you can use it in your automation scripts and external integrations. This eliminates the need to share your personal token anywhere.

Risk mitigation
Since Management Tokens can be invalidated anytime, it helps in mitigating risks in scenarios where the token is compromised.

How is it different from Authtoken

An Authtoken is a read-write token used to make authorized CMA requests, but it is a user-specific token. This means that your personal user details are attached to every API request that you make using the authtoken. So, if a person were to obtain access to your authtoken, and knows the Stack API key, this person would be able to make API requests that appeared to be coming from you.

Management Tokens, on the other hand, are stack-level tokens, with no users attached to them. They can do everything that authtokens can do (with a few exceptions). Since they are not personal tokens, no role-specific permissions are applicable to them. It is recommended to use these tokens for automation scripts, third-party app integrations, and for Single Sign On (SSO)-enabled organizations.

Note: Only the owner or admin of a stack can create management tokens.

Generate a Management Token

To create a new management token, perform the steps given below:

Note: Only the stack Owners and Admins can create management tokens.

1. Navigate to Settings > Tokens.
2. Under the Management Tokens tab, click on Add Token.
3. Provide a relevant Name and Description for the token.
4. Under Permissions, select the stack-level permissions you want to assign to this token, for eg. Read. Read the Capabilities of Management Token section for more details.
   
5. Under Expiry, set an expiration limit for this management token. Select the Date (in UTC) option and choose a specific expiry date from the calendar.
   
   

   Note: Once you set the expiration limit, the management token expires at midnight (UTC time) of the specified date.

   You can alternatively keep the Never option selected if you do not want the token to have an expiration limit.
   
   Once a token has expired, it becomes invalid and it cannot be used to make any content management API calls.
6. Additionally, you can select the Notify via email checkbox to turn on email notifications when a token nears its expiry date. The owner or admin of the stack will be notified by email 7 days before the token expires.
7. Click on Generate Token.
   
8. Once you click on Generate Token, the management token will be visible on the dialog that appears. Copy the token for future reference, since it will not be visible once you close the dialog.

You will be able to use the generated token to make authorized Content Management API requests at the stack level.

Note: You can generate multiple management tokens for a specific stack within your organization. However, there is a maximum limit of 10 valid tokens that can exist per stack at a time, to execute CMA requests. If you already have 10 valid tokens, creating a new management token will automatically cause the oldest management token to expire without warning.

Tutorial Video

Let's see how to create a management token.

Edit a Management Token

To edit the details of the token, follow the steps given below:

1. Navigate to Settings > Tokens.
2. In the Management Tokens tab, click on the token to edit.
3. Edit the details. You can change the name, description, expiry date, and permission or enable/disable "Notify via email". Note that you cannot edit or view the token value.
   
4. Save the changes.

Delete a Management Token

To delete an existing management token, perform the steps given below:

1. Navigate to Settings > Tokens > Management Tokens.
2. Hover over the token that you want to delete. On the extreme right side, you will notice a vertical ellipsis icon (three dots), which is the More Options icon.
3. Click on the ellipses and select Delete to remove the management token.
   
4. In the Delete Management Token dialog, type the name of the token and click Delete.
   

This will permanently delete the management token.

Limitations

• A maximum of 10 management tokens can exist at a time in a specific stack.
• A management token can only be generated by the owner or admin of a stack.
• A management token cannot be used for the following modules: organization, stack, user session, and tokens.
• A management token cannot be used to accept/reject a received publish/unpublish request for an entry.
• A management token cannot be used to invite users to and remove users from the stack
  

Delivery Tokens

Delivery Tokens provide read-only access to the associated environments. It is a credential—used along with the stack API key—to make authorized Content Delivery API requests for retrieving the published content of an environment.

By default, Contentstack does not provide any delivery tokens. You need to create new tokens for the environments of your stack.

However, one token can be used to fetch content from only one environment. This means that you need to create different tokens for different publishing environments of your stack.

Having separate tokens for different environments ensure that only the specified people have access to the content of the required environments. For example, testers can have fetch content of only the ‘staging’ environment, while content managers have access to the ‘production’ environment. This separation ensures the safety of your content and allows you to manage separate delivery channels independently.

Key points to remember:

• You can associate a delivery token with only one environment. Consequently, you need to create different tokens for different environments.
• Delivery tokens can be used to fetch only published content, not unpublished or draft content.
• You can create a maximum of 20 tokens in a stack.

Create a delivery token

To create a new delivery token, perform the steps given below:

1. Navigate to Settings > Tokens. 
2. Select Add Token.
3. Provide a relevant Name and Description for the token.
4. Under Scope, select the Environment for which you want to create this token.
   
5. Click Generate Token. You will see a new token in the Delivery Token field.

You will be able to use the generated token to fetch the content of only the selected environment. It cannot be used to fetch the content of any other environment.

Note: Only the stack Owners, Developers, and Admin can create delivery tokens.

Tutorial Video

Let's see how to create a delivery token.

Edit a delivery token

To edit the details of the token, follow the steps given below:

1. Navigate to Settings > Tokens.
2. Click on the token to edit. 
3. Edit the details.
   
4. Click Save to save the changes.

Delete a delivery token

To delete an existing delivery token, perform the steps given below:

1. Navigate to Settings > Tokens.
2. Hover on the token that you want to delete. On the right side corner, you will notice vertical ellipses. Click on the ellipses and select ‘Delete’ to remove the delivery token.
   
   

Different Types of Tokens

Contentstack provides different types of tokens to authorize API calls. Let us look at the key features of these tokens to understand their characteristics.