ManagementToken

View as Markdown

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 NameReturnsDescription
queryA query for management tokens, sent when you call find(), findOne() or count().Lists the management tokens of the stack.
createThe new management token.Creates a management token.

Work with one management token. Available on stack.managementToken('<TOKEN_UID>').

Method NameReturnsDescription
fetchThe requested management token.Fetches the details of one management token.
updateThe updated management token.Saves new details, permissions or expiry.
deleteThe API response with a notice.Deletes a management token.

Set headers. Available on both forms.

Method NameReturnsDescription
addHeaderThe same management token, for chaining.Adds one header to the object.
addHeaderDictThe same management token, for chaining.Adds several headers to the object.
removeHeaderThe 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.

NameTypeDescription
key (required)string

Name of the header, for example x-request-id.

Default: Not applicable
value (required)string

Value to send in the header.

Default: Not applicable

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.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

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.

NameTypeDescription
data (required)object

Details of the token, under a token key.

Default: Not applicable
data.token.name (required)string

Name of the management token.

Default: Not applicable
data.token.descriptionstring

Description of the management token.

Default: undefined
data.token.scope (required)Scope[]

Modules, branches and aliases with their permissions.

Default: Not applicable
data.token.expires_onstring

Expiry date of the token, in UTC.

Default: undefined
data.token.is_email_notification_enabledboolean

Emails you seven days before the token expires.

Default: undefined
paramobject

Query parameters for the request. The API lists none.

Default: undefined (sends no query parameters)

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.

NameTypeDescription
paramAnyProperty

Query parameters for the request. The API lists none.

Default: {} (sends no query parameters)

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.

NameTypeDescription
paramAnyProperty

Query parameters for the request. The API lists none.

Default: {} (sends no query parameters)

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.

NameTypeDescription
paramsobject

Query parameters for the request. The API lists none.

Default: {}

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.

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

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.

NameTypeDescription
paramAnyProperty

Query parameters for the request. The API lists none.

Default: {} (sends no query parameters)

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)
}