Tokens
Contentstack provides different types of tokens to authorize API requests. You can use Delivery Tokens to authenticate Content Delivery API (CDA) requests and retrieve the published content of an environment. To authenticate Content Management API (CMA) requests over your stack content, you can use Management Tokens.
Delivery tokens provide read-only access to the associated environments, while management tokens provide read-write access to the content of your stack. Use these tokens along with the stack API key to make authorized API requests.
Get all delivery tokens
https://api.contentstack.io/v3/stacks/delivery_tokensThe Get all delivery tokens request returns the details of all the delivery tokens created in a stack.
{
"tokens":[
{
"name":"Test",
"scope":[
{
"environments":[
{
"deploy_content":false,
"servers":[
],
"urls":[
{
"url":"http://www.sample.com",
"locale":"en-us"
}
],
"name":"production",
"app_user_object_uid":"system",
"uid":"bltc123123ab6c32126",
"created_by":"blt7d123cc321ee12e",
"updated_by":"blt7d123cc321ee12e",
"created_at":"2019-07-15T07:26:10.915Z",
"updated_at":"2019-07-15T07:26:10.915Z",
"ACL":[
],
"_version":1,
"tags":[
]
}
],
"module":"environment",
"acl":{
"read":true
}
},
{
"module":"branch",
"acl":{
"read":true
},
"branches":[
"main",
"development"
],
"_metadata":{
"uid":"cs766df728fb56e697"
}
},
{
"module":"branch_alias",
"acl":{
"read":true
},
"branch_aliases":[
"deploy",
"release"
],
"_metadata":{
"uid":"cs27a40bf57db84414"
}
}
],
"uid":"bltdce123123d321f3",
"created_by":"blt7d123cc321ee12e",
"updated_by":"blt7d123cc321ee12e",
"created_at":"2019-07-19T07:41:05.070Z",
"updated_at":"2019-07-19T07:41:05.070Z",
"description":"",
"token":"csf72faf222222e222ddd2222b",
"type":"delivery"
}
]
}Get a single delivery token
https://api.contentstack.io/v3/stacks/delivery_tokens/{token_uid}The Get a single delivery token request returns the details of a particular delivery token created in a stack.
{
"tokens":[
{
"name":"Test",
"scope":[
{
"environments":[
{
"deploy_content":false,
"servers":[
],
"urls":[
{
"url":"http://www.sample.com",
"locale":"en-us"
}
],
"name":"production",
"app_user_object_uid":"system",
"uid":"bltc123123ab6c32126",
"created_by":"blt7d123cc321ee12e",
"updated_by":"blt7d123cc321ee12e",
"created_at":"2019-07-15T07:26:10.915Z",
"updated_at":"2019-07-15T07:26:10.915Z",
"ACL":[
],
"_version":1,
"tags":[
]
}
],
"module":"environment",
"acl":{
"read":true
}
},
{
"module":"branch",
"acl":{
"read":true
},
"branches":[
"main",
"development"
],
"_metadata":{
"uid":"cs766df728fb56e697"
}
},
{
"module":"branch_alias",
"acl":{
"read":true
},
"branch_aliases":[
"deploy",
"release"
],
"_metadata":{
"uid":"cs27a40bf57db84414"
}
}
],
"uid":"bltdce123123d321f3",
"created_by":"blt7d123cc321ee12e",
"updated_by":"blt7d123cc321ee12e",
"created_at":"2019-07-19T07:41:05.070Z",
"updated_at":"2019-07-19T07:41:05.070Z",
"description":"",
"token":"csf72faf222222e222ddd2222b",
"type":"delivery"
}
]
}Create delivery token
https://api.contentstack.io/v3/stacks/delivery_tokensThe Create delivery token request is used to create a delivery token in the stack.
In the Request Body, you need to pass the details of the delivery token in JSON format. The details include the name, description, and the environment of the delivery token.
To create a delivery token with associated preview token, pass the create_with_preview_token query parameter as true.
NoteIt is highly recommended to set only one publishing environment per delivery token.
You need to specify the branch and alias scope for your delivery token through the following schema in the request body:
{
"module":"branch",
"branches":[
"main",
"development"
],
"acl":{
"read":true
}
},
{
"module":"branch_alias",
"branch_aliases":[
"deploy",
"release"
],
"acl":{
"read":true
}
}{
"token": {
"name": "Sample Delivery Token",
"description": "This is a sample delivery token.",
"scope": [{
"module": "environment",
"environments": ["production"],
"acl": {
"read": true
}
}]
}
}{
"notice": "Delivery Token created successfully.",
"token": {
"name": "Sample Delivery Token",
"description": "This is a sample delivery token.",
"scope": [
{
"environments": [
{
"urls": [
{
"url": "",
"locale": "en-us"
}
],
"name": "production",
"_version": 2,
"app_user_object_uid": "system",
"uid": "bltb3c6cea2fefce1a6",
"created_by": "blt0f1b34d48616093a",
"updated_by": "blt0f1b34d48616093a",
"created_at": "2023-06-26T12:15:12.745Z",
"updated_at": "2023-06-26T12:15:12.745Z",
"ACL": [],
"tags": []
}
],
"module": "environment",
"acl": {
"read": true
},
"_metadata": {
"uid": "cse639d7ef7edf687b"
}
}
],
"preview_token": "cs76f46e9817405ec92b1d2dc1",
"uid": "blt8041e844c449278a",
"created_by": "blt0a9cc7075b8decf0",
"updated_by": "blt0a9cc7075b8decf0",
"created_at": "2023-11-29T10:45:40.826Z",
"updated_at": "2023-11-29T10:45:40.826Z",
"token": "csb2d9c0f6158aff22d9e09460",
"type": "delivery"
}
}Update delivery token
https://api.contentstack.io/v3/stacks/delivery_tokens/{token_uid}The Update delivery token request lets you update the details of a delivery token.
In the Request Body, you need to pass the updated details of the delivery token in JSON format. The details include the updated name, description, and/or the environment of the delivery token.
You need to specify the branch and alias scope for your delivery token through the following schema in the request body:
{
"module":"branch",
"branches":[
"main",
"development"
],
"acl":{
"read":true
}
},
{
"module":"branch_alias",
"branch_aliases":[
"deploy",
"release"
],
"acl":{
"read":true
}
}{
"token":{
"name":"Test",
"description":"This is a updated token.",
"scope":[
{
"module":"environment",
"environments":[
"production"
],
"acl":{
"read":true
}
},
{
"module":"branch",
"branches":[
"main",
"development"
],
"acl":{
"read":true
}
},
{
"module":"branch_alias",
"branch_aliases":[
"deploy"
],
"acl":{
"read":true
}
}
]
}
}{
"notice:":"Delivery token updated successfully",
"tokens":[
{
"name":"Test",
"scope":[
{
"environments":[
{
"deploy_content":false,
"servers":[
],
"urls":[
{
"url":"http://www.sample.com",
"locale":"en-us"
}
],
"name":"production",
"app_user_object_uid":"system",
"uid":"bltc123123ab6c32126",
"created_by":"blt7d123cc321ee12e",
"updated_by":"blt7d123cc321ee12e",
"created_at":"2019-07-15T07:26:10.915Z",
"updated_at":"2019-07-15T07:26:10.915Z",
"ACL":[
],
"_version":1,
"tags":[
]
}
],
"module":"environment",
"acl":{
"read":true
}
},
{
"module":"branch",
"acl":{
"read":true
},
"branches":[
"main",
"development"
],
"_metadata":{
"uid":"csee4be95096e55c10"
}
},
{
"module":"branch_alias",
"acl":{
"read":true
},
"branch_aliases":[
"deploy"
],
"_metadata":{
"uid":"cs930edafb5eaf80e7"
}
}
],
"uid":"bltdce123123d321f3",
"created_by":"blt7d123cc321ee12e",
"updated_by":"blt7d123cc321ee12e",
"created_at":"2019-07-19T07:41:05.070Z",
"updated_at":"2019-07-19T07:41:05.070Z",
"description":"This is a updated token.",
"token":"csf72faf222222e222ddd2222b",
"type":"delivery"
}
]
}Delete delivery token
https://api.contentstack.io/v3/stacks/delivery_tokens/{token_uid}?force={boolean_value}The Delete delivery token request deletes a specific delivery token.
{
"notice:": "Delivery Token deleted successfully."
}Create preview token
https://api.contentstack.io/v3/stacks/delivery_tokens/{delivery_token_uid}/preview_tokenThe Create preview token request creates a Preview token for a particular Delivery token in a stack of your organization.
{
"notice": "Preview token created successfully.",
"token": {
"name": "Sample Delivery Token",
"description": "This is a sample delivery token.",
"scope": [
{
"environments": [
{
"urls": [
{
"url": "",
"locale": "en-us"
}
],
"name": "production",
"_version": 2,
"app_user_object_uid": "system",
"uid": "bltb3c6cea2fefce1a6",
"created_by": "blt0f1b34d48616093a",
"updated_by": "blt0f1b34d48616093a",
"created_at": "2023-06-26T12:15:12.745Z",
"updated_at": "2023-06-26T12:15:12.745Z",
"ACL": [],
"tags": []
}
],
"module": "environment",
"acl": {
"read": true
},
"_metadata": {
"uid": "cs965b4bfbe0afec6b"
}
}
],
"uid": "blt8041e844c449278a",
"created_by": "blt0a9cc7075b8decf0",
"updated_by": "blt0a9cc7075b8decf0",
"created_at": "2023-11-29T10:45:40.826Z",
"updated_at": "2023-11-29T10:47:53.587Z",
"token": "csb2d9c0f6158aff22d9e09460",
"type": "delivery",
"preview_token": "cs0d1431d6a4f8fe3d10b1861c"
}
}Delete preview token
https://api.contentstack.io/v3/stacks/delivery_tokens/{delivery_token_uid}/preview_tokenThe Delete preview token request deletes a preview token associated with a specific delivery token.
{
"notice": "Preview token deleted successfully."
}A Preview Token provides you access to retrieve details of your website within the live preview panel.
NoteThe Preview tokens are exclusively compatible with the new rest-preview.contentstack.com endpoint.
Get all management tokens
https://api.contentstack.io/v3/stacks/management_tokensThe Get all management tokens request returns the details of all the management tokens generated in a stack and not the actual management tokens.
{
"tokens":[
{
"name":"Test Token",
"expires_on":"2020-12-10",
"is_email_notification_enabled":true,
"scope":[
{
"module":"content_type",
"acl":{
"read":true,
"write":true
}
},
{
"module":"branch",
"acl":{
"read":true
},
"branches":[
"main",
"development"
]
},
{
"module":"branch_alias",
"acl":{
"read":true
},
"branch_aliases":[
"deploy"
]
}
],
"uid":"bltds822f23g4d28hg2",
"created_by":"blt6563a9b067fc1bc9",
"updated_by":"blt6563a9b067fc1bc9",
"created_at":"2020-11-12T09:32:12.239Z",
"updated_at":"2020-11-12T09:32:12.239Z",
"description":"This is a sample management token."
},
{
"name":"Sample Token",
"expires_on":"2020-11-27",
"is_email_notification_enabled":true,
"scope":[
{
"module":"$all",
"acl":{
"read":true,
"write":true
}
},
{
"module":"branch",
"acl":{
"read":true
},
"branches":[
"main",
"development"
]
},
{
"module":"branch_alias",
"acl":{
"read":true
},
"branch_aliases":[
"deploy"
]
}
],
"uid":"bltcde433gf0967fdac",
"created_by":"blt6563a9b067fc1bc9",
"updated_by":"blt6563a9b067fc1bc9",
"created_at":"2020-11-12T09:24:57.191Z",
"updated_at":"2020-11-12T09:24:57.191Z",
"description":"This is a sample token."
}
]
}Get a single management token
https://api.contentstack.io/v3/stacks/management_tokens/{token_uid}The Get a single management token request returns the details of a specific management token generated in a stack and not the actual management token.
{
"token":{
"name":"Test Token",
"expires_on":"2020-12-10",
"is_email_notification_enabled":true,
"scope":[
{
"module":"content_type",
"acl":{
"read":true,
"write":true
}
},
{
"module":"branch",
"acl":{
"read":true
},
"branches":[
"main",
"development"
]
},
{
"module":"branch_alias",
"acl":{
"read":true
},
"branch_aliases":[
"deploy"
]
}
],
"uid":"bltda613c24d4e12c28",
"created_by":"blt6563a9b067fc1bc9",
"updated_by":"blt6563a9b067fc1bc9",
"created_at":"2020-11-12T09:32:12.239Z",
"updated_at":"2020-11-12T09:32:12.239Z",
"description":"This is a sample management token."
}
}Create management token
https://api.contentstack.io/v3/stacks/management_tokensThe Create management token request is used to create a management token in a stack. This token provides you with read-write access to the content of your stack.
NoteA management token can only be generated by the owner or admin of a stack.
In the Request Body, you need to pass the details of the management token in JSON format. The details include the name, description, the stack-level permissions you need to assign to the token, and the expiry date of the token in UTC time (if required). Additionally, you can also choose to get notified (via email) seven days before the token expires.
You need to specify the branch and alias scope for your management token through the following schema in the request body:
{
"module":"branch",
"branches":[
"main",
"development"
],
"acl":{
"read":true
}
},
{
"module":"branch_alias",
"branch_aliases":[
"deploy",
"release"
],
"acl":{
"read":true
}
}
NoteYou can generate a maximum of 10 management tokens for a specific stack within your organization.
{
"token":{
"name":"Test Token",
"description":"This is a sample management token.",
"scope":[
{
"module":"content_type",
"acl":{
"read":true,
"write":true
}
},
{
"module":"branch",
"branches":[
"main",
"development"
],
"acl":{
"read":true
}
},
{
"module":"branch_alias",
"branch_aliases":[
"deploy",
"release"
],
"acl":{
"read":true
}
}
],
"expires_on":"2020-12-10",
"is_email_notification_enabled":true
}
}{
"notice":"Management Token created successfully.",
"token":{
"name":"Test Token",
"description":"This is a sample management token.",
"scope":[
{
"module":"content_type",
"acl":{
"read":true,
"write":true
}
},
{
"module":"branch",
"acl":{
"read":true
},
"branches":[
"main",
"development"
]
},
{
"module":"branch_alias",
"acl":{
"read":true
},
"branch_aliases":[
"deploy",
"release"
]
}
],
"expires_on":"2020-12-10",
"is_email_notification_enabled":true,
"uid":"blt3b10e39122774473",
"created_by":"blt6563a9b067fc1bc9",
"updated_by":"blt6563a9b067fc1bc9",
"created_at":"2020-11-12T09:04:49.561Z",
"updated_at":"2020-11-12T09:04:49.561Z",
"token":"cs808c053abc70fe2ccda123b2"
}
}Update management token
https://api.contentstack.io/v3/stacks/management_tokens/{token_uid}The Update management token request lets you update the details of a management token. You can change the name and description of the token; update the stack-level permissions assigned to the token; and change the expiry date of the token (if set).
In the Request Body, you need to pass the updated details of the management token in JSON format.
To specify the updated branch and alias scope for your management token, use the following schema in the request body:
{
"module":"branch",
"branches":[
"main",
"development"
],
"acl":{
"read":true
}
},
{
"module":"branch_alias",
"branch_aliases":[
"deploy",
"release"
],
"acl":{
"read":true
}
}{
"token":{
"name":"Updated Test Token",
"description":"This is an updated management token.",
"scope":[
{
"module":"content_type",
"acl":{
"read":true,
"write":true
}
},
{
"module":"entry",
"acl":{
"read":true,
"write":true
}
},
{
"module":"branch",
"branches":[
"main",
"development"
],
"acl":{
"read":true
}
},
{
"module":"branch_alias",
"branch_aliases":[
"deploy"
],
"acl":{
"read":true
}
}
],
"expires_on":"2020-12-31",
"is_email_notification_enabled":true
}
}{
"notice":"Management Token updated successfully.",
"token":{
"name":"Updated Test Token",
"description":"This is an updated management token.",
"scope":[
{
"module":"content_type",
"acl":{
"read":true,
"write":true
}
},
{
"module":"entry",
"acl":{
"read":true,
"write":true
}
},
{
"module":"branch",
"acl":{
"read":true
},
"branches":[
"main",
"development"
]
},
{
"module":"branch_alias",
"acl":{
"read":true
},
"branch_aliases":[
"deploy"
]
}
],
"expires_on":"2020-12-31",
"is_email_notification_enabled":true,
"uid":"blt4d23e29233884473",
"created_by":"blt6563a9b067fc1bc9",
"updated_by":"blt6563a9b067fc1bc9",
"created_at":"2020-11-12T09:04:49.561Z",
"updated_at":"2020-11-12T09:21:02.244Z"
}
}Delete management token
https://api.contentstack.io/v3/stacks/management_tokens/{token_uid}The Delete management token request deletes a specific management token.
{
"notice": "Management Token deleted successfully."
}