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 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 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.
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.
A management token with READ & WRITE permissions can perform all actions on the following modules:
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.
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.
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.
To create a new management token, perform the steps given below:
Note: Only the stack Owners and Admins can create management tokens.
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.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.
Let's see how to create a management token.
To edit the details of the token, follow the steps given below:
To delete an existing management token, perform the steps given below:
This will permanently delete the management token.
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:
To create a new delivery token, perform the steps given below:
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.
Let's see how to create a delivery token.
To edit the details of the token, follow the steps given below:
To delete an existing delivery token, perform the steps given below:
Contentstack provides different types of tokens to authorize API calls. Let us look at the key features of these tokens to understand their characteristics.