ManagementToken
ManagementToken
A ManagementToken manages the management tokens of one stack. A management token gives read-write access to the content of the stack through the Content Management API (CMA), without a user login.
Use this class to
- list the management tokens of a stack
- fetch the details of one management token
- create a management token with stack-level permissions and an optional expiry date
- update or delete a management token
Instance State
Get a ManagementToken from the managementToken method of a stack opened with an API key.
- Call stack.managementToken() to work with all management tokens, for example through create or query.
- Call stack.managementToken('<TOKEN_UID>') to work with one token, for example through fetch, update or delete.
A method of the other form is undefined, so calling it throws TypeError. For example, stack.managementToken().fetch() throws. An empty string as the UID returns the stack.managementToken() form, as null does.
The objects that create, fetch and update resolve to, and the items of a query result, are in the UID form.
Class-Level Notes
Authentication.
- Every management token request of the CMA requires an authtoken and the stack API key, as the Management Token Collection reference lists. Use contentstack.client({ authtoken: '<AUTHTOKEN>' }), or log in, then open the stack with client.stack({ api_key: '<API_KEY>' }).
- Only the owner or an admin of the stack can create a management token, as the API reference states.
Token values.
- The fetch and list requests return the details of a management token, not the token itself, as the API reference states.
Headers.
- A ManagementToken shares the header map of the stack it came from, which holds api_key and, when set, branch.
- The first call to addHeader, addHeaderDict or removeHeader on the object copies that map. From then on, the object keeps its own copy.
Rate limiting and retry.
- This SDK retries a request that receives 429 automatically, with configurable delay and attempt limits.
Additional Resource For more information on the retry settings and their defaults, refer to the Contentstack documentation.
Method Index
Work with all management tokens. Available on stack.managementToken().
| Method Name | Returns | Description |
|---|---|---|
| query | A query for management tokens, sent when you call find(), findOne() or count(). | Lists the management tokens of the stack. |
| create | The new management token. | Creates a management token. |
Work with one management token. Available on stack.managementToken('<TOKEN_UID>').
| Method Name | Returns | Description |
|---|---|---|
| fetch | The requested management token. | Fetches the details of one management token. |
| update | The updated management token. | Saves new details, permissions or expiry. |
| delete | The API response with a notice. | Deletes a management token. |
Set headers. Available on both forms.
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same management token, for chaining. | Adds one header to the object. |
| addHeaderDict | The same management token, for chaining. | Adds several headers to the object. |
| removeHeader | The same management token, for chaining. | Removes one header from the object. |
Class-Level Snippet
The snippet below lists the management tokens of a stack and prints the name of each.
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const result = await stack.managementToken().query().find()
result.items.forEach((managementToken) => console.log(managementToken.name))
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Methods
Each method of the ManagementToken class has its own section below, with its parameters, validation rules, behavior, and examples.
addHeader
addHeader adds one request header to the management token object, for every request it sends afterwards.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header, for example x-request-id. |
| value (required) | string | Value to send in the header. |
Returns: ManagementToken. The same management token, for chaining.
Validation
- There is no client-side validation of the header name or value. addHeader ignores a null or undefined key and returns the object unchanged.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeader changes the management token object's header map and sends no request.
- Until its first header change, the management token object shares the header map of the stack it came from, so headers you add to the stack reach it. The first call to addHeader, addHeaderDict or removeHeader copies that map, and from then on the change applies to this object only. The stack and its other objects keep their headers.
- Every later request of this object sends the map. So do the objects that create, fetch and update resolve to. A query from query() copies the map when you call query().
- A second call with the same key replaces the value, including the api_key and branch headers that the object inherited.
Example
Basic usage: tag the requests of one management token with a request ID
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
const managementToken = stack.managementToken('<TOKEN_UID>').addHeader('x-request-id', 'docs-123')
console.log(managementToken.stackHeaders)addHeaderDict
addHeaderDict adds several request headers to the management token object at once, for every request it sends afterwards.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
Returns: ManagementToken. The same management token, for chaining.
Validation
- There is no client-side validation of the header names or values. addHeaderDict ignores null, undefined and any value that is not an object, and returns the object unchanged.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeaderDict changes the management token object's header map and sends no request.
- Until its first header change, the management token object shares the header map of the stack it came from, so headers you add to the stack reach it. The first call to addHeader, addHeaderDict or removeHeader copies that map, and from then on the change applies to this object only. The stack and its other objects keep their headers.
- Every later request of this object sends the map. So do the objects that create, fetch and update resolve to. A query from query() copies the map when you call query().
- A key that already exists takes the new value.
Example
Basic usage: add two headers to one management token
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
const managementToken = stack.managementToken('<TOKEN_UID>').addHeaderDict({
'x-request-id': 'docs-123',
'x-team': 'web'
})
console.log(managementToken.stackHeaders)create
create creates a management token with the stack-level permissions in its scope.
| Name | Type | Description |
|---|---|---|
| data (required) | object | Details of the token, under a token key. |
| data.token.name (required) | string | Name of the management token. |
| data.token.description | string | Description of the management token. |
| data.token.scope (required) | Scope[] | Modules, branches and aliases with their permissions. |
| data.token.expires_on | string | Expiry date of the token, in UTC. |
| data.token.is_email_notification_enabled | boolean | Emails you seven days before the token expires. |
| param | object | Query parameters for the request. The API lists none. |
Returns: Promise<ManagementToken>. The new management token.
Validation
- There is no client-side validation. create sends data unchanged as the body.
- create exists only on stack.managementToken(). On stack.managementToken('<TOKEN_UID>') it is undefined, and calling it throws TypeError.
- The API rejects the request from a user who is not the owner or an admin of the stack, as the Create management token reference states.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one Create management token request (POST /stacks/management_tokens) with the object's headers, and data as the body.
- Each item of data.token.scope names a module and an acl. A content module, such as content_type, takes acl permissions such as read and write. A branch module takes branches, and a branch_alias module takes branch_aliases.
- Resolves to a new ManagementToken in the UID form, which the SDK builds from the token key of the response.
Example
Basic usage: create a token that reads and writes content types on the main branch
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const managementToken = await stack.managementToken().create({
token: {
name: 'docs-test-management-token',
scope: [
{ module: 'content_type', acl: { read: true, write: true } },
{ module: 'branch', branches: ['main'], acl: { read: true } }
]
}
})
console.log(managementToken.uid)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: create a token with an alias scope, an expiry date and an email reminder
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const managementToken = await stack.managementToken().create(
{
token: {
name: 'docs-test-deploy-token',
description: 'Token for the deployment pipeline',
scope: [
{ module: 'content_type', acl: { read: true, write: true } },
{ module: 'branch_alias', branch_aliases: ['<ALIAS_UID>'], acl: { read: true } }
],
expires_on: '2027-12-31',
is_email_notification_enabled: true
}
},
{}
)
console.log(managementToken.uid, managementToken.expires_on)
} catch (error) {
console.error(error.errorMessage)
}delete
delete permanently deletes one management token.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. The API lists none. |
Returns: Promise<Response>. The API response with a notice.
Warning Every script or integration that sends this token loses access to the stack when you delete it. You cannot restore the token. Create a new one and update those scripts with its value.
Validation
- There is no client-side validation.
- delete exists only on stack.managementToken('<TOKEN_UID>') and on the objects that fetch, create and query return. On stack.managementToken() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one Delete management token request (DELETE /stacks/management_tokens/{token_uid}) with the object's headers, and every key of param as a query parameter.
- Resolves to the response body, which carries notice.
Example
Basic usage: delete a management token
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const response = await stack.managementToken('<TOKEN_UID>').delete({})
console.log(response.notice)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}fetch
fetch retrieves the details of one management token, such as its name, scope and expiry date.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. The API lists none. |
Returns: Promise<ManagementToken>. The requested management token.
Validation
- There is no client-side validation.
- fetch exists only on stack.managementToken('<TOKEN_UID>'). On stack.managementToken() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one Get a single management token request (GET /stacks/management_tokens/{token_uid}) with the object's headers, and every key of param as a query parameter.
- The response holds the details of the token, not the token value, as the API reference states.
- Resolves to a new ManagementToken, which the SDK builds from the token key of the response.
Example
Basic usage: fetch one management token
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const managementToken = await stack.managementToken('<TOKEN_UID>').fetch()
console.log(managementToken.name, managementToken.scope)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: pass a query parameters object
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const managementToken = await stack.managementToken('<TOKEN_UID>').fetch({})
console.log(managementToken.name)
} catch (error) {
console.error(error.errorMessage)
}query
query builds a query for the management tokens of the stack.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters for the request. The API lists none. |
Returns: Query. A query for management tokens, sent when you call find(), findOne() or count().
Validation
- There is no client-side validation.
- query exists only on stack.managementToken(). On stack.managementToken('<TOKEN_UID>') it is undefined, and calling it throws TypeError.
- An invalid value surfaces as a rejected promise from the request method you call next.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. query sends no request. The find, findOne and count methods of the returned Query send the Get all management tokens request (GET /stacks/management_tokens).
- The response holds the details of each token, not the token values, as the API reference states.
- query copies the object's headers when you call it. A header you add to the management token object later does not reach the query.
- Each item in the items array of the find result is a ManagementToken in the UID form, with methods such as fetch and delete.
Example
Basic usage: list the name of each management token
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const result = await stack.managementToken().query().find()
result.items.forEach((managementToken) => console.log(managementToken.name))
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: pass a query parameters object
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const result = await stack.managementToken().query({}).find()
console.log(result.items.length)
} catch (error) {
console.error(error.errorMessage)
}removeHeader
removeHeader removes one request header from the management token object, for every request it sends afterwards.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
Returns: ManagementToken. The same management token, for chaining.
Validation
- There is no client-side validation. removeHeader ignores a null or undefined key and returns the object unchanged.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. removeHeader changes the management token object's header map and sends no request.
- Until its first header change, the management token object shares the header map of the stack it came from, so headers you add to the stack reach it. The first call to addHeader, addHeaderDict or removeHeader copies that map, and from then on the change applies to this object only. The stack and its other objects keep their headers.
- Every later request of this object sends the map. So do the objects that create, fetch and update resolve to. A query from query() copies the map when you call query().
- When the map has no header named key, removeHeader changes nothing and does not copy the map.
- The management token that client.stack({ management_token }) sets lives in the client's defaults, not in this map. removeHeader('authorization') does not remove it.
Example
Basic usage: remove a header from one management token
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
const managementToken = stack.managementToken('<TOKEN_UID>')
.addHeader('x-request-id', 'docs-123')
.removeHeader('x-request-id')
console.log(managementToken.stackHeaders)update
update saves the name, description, permissions and expiry date that you set on the management token object.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. The API lists none. |
Returns: Promise<ManagementToken>. The updated management token.
Validation
- There is no client-side validation.
- update exists only on stack.managementToken('<TOKEN_UID>') and on the objects that fetch, create and query return. On stack.managementToken() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one Update management token request (PUT /stacks/management_tokens/{token_uid}) with the object's headers.
- update builds the request body from the object's own properties, under a token key. It leaves out uid, api_key, the created_*, updated_* and deleted_at fields, and the methods. On an object from fetch, the body also carries the other fetched properties.
- The API reference lists the name, the description, the stack-level permissions in scope and the expiry date as the details you can change.
- Resolves to a new ManagementToken, which the SDK builds from the response.
Example
Basic usage: rename a management token
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const managementToken = await stack.managementToken('<TOKEN_UID>').fetch()
managementToken.name = 'Deployment pipeline token'
managementToken.description = 'Token for the deployment pipeline'
const updatedToken = await managementToken.update()
console.log(updatedToken.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: change the permissions and pass a query parameters object
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const managementToken = await stack.managementToken('<TOKEN_UID>').fetch()
managementToken.scope = [
{ module: 'content_type', acl: { read: true, write: false } },
{ module: 'branch', branches: ['main', '<BRANCH>'], acl: { read: true } }
]
const updatedToken = await managementToken.update({})
console.log(updatedToken.scope)
} catch (error) {
console.error(error.errorMessage)
}