DeliveryToken

View as Markdown

DeliveryToken

A DeliveryToken manages the delivery tokens of one stack. A delivery token gives read-only access to the published content of the environments in its scope, through the Content Delivery API (CDA).

Use this class to

  • list the delivery tokens of a stack
  • fetch the details of one delivery token
  • create a delivery token for an environment and a branch
  • update or delete a delivery token
  • create or delete the preview token of a delivery token

Instance State

Get a DeliveryToken from the deliveryToken method of a stack opened with an API key.

  • Call stack.deliveryToken() to work with all delivery tokens, for example through create or query.
  • Call stack.deliveryToken('<TOKEN_UID>') to work with one token, for example through fetch, update or previewToken.

A method of the other form is undefined, so calling it throws TypeError. For example, stack.deliveryToken().fetch() throws. An empty string as the UID returns the stack.deliveryToken() 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 delivery token request of the Content Management API (CMA) requires an authtoken and the stack API key, as the Delivery Token Collection reference lists. Use contentstack.client({ authtoken: '<AUTHTOKEN>' }), or log in, then open the stack with client.stack({ api_key: '<API_KEY>' }).

Headers.

  • A DeliveryToken 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 delivery tokens. Available on stack.deliveryToken().

Method NameReturnsDescription
queryA query for delivery tokens, sent when you call find(), findOne() or count().Lists the delivery tokens of the stack.
createThe new delivery token.Creates a delivery token.

Work with one delivery token. Available on stack.deliveryToken('<TOKEN_UID>').

Method NameReturnsDescription
fetchThe requested delivery token.Fetches the details of one delivery token.
updateThe updated delivery token.Saves a new name, description or scope.
deleteThe API response with a notice.Deletes a delivery token.
previewTokenA new preview token object.Opens the preview token of the delivery token.

Set headers. Available on both forms.

Method NameReturnsDescription
addHeaderThe same delivery token, for chaining.Adds one header to the object.
addHeaderDictThe same delivery token, for chaining.Adds several headers to the object.
removeHeaderThe same delivery token, for chaining.Removes one header from the object.

Class-Level Snippet

The snippet below lists the delivery 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.deliveryToken().query().find()
  result.items.forEach((deliveryToken) => console.log(deliveryToken.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 DeliveryToken class has its own section below, with its parameters, validation rules, behavior, and examples.

addHeader

addHeader adds one request header to the delivery 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: DeliveryToken. The same delivery 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 delivery token object's header map and sends no request.
  • Until its first header change, the delivery 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, and the PreviewToken object from previewToken(). 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 delivery 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 deliveryToken = stack.deliveryToken('<TOKEN_UID>').addHeader('x-request-id', 'docs-123')
console.log(deliveryToken.stackHeaders)

addHeaderDict

addHeaderDict adds several request headers to the delivery token object at once, for every request it sends afterwards.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

Returns: DeliveryToken. The same delivery 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 delivery token object's header map and sends no request.
  • Until its first header change, the delivery 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, and the PreviewToken object from previewToken(). 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 delivery token

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

const deliveryToken = stack.deliveryToken('<TOKEN_UID>').addHeaderDict({
  'x-request-id': 'docs-123',
  'x-team': 'web'
})
console.log(deliveryToken.stackHeaders)

create

create creates a delivery token for the environments, branches and aliases 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 delivery token.

Default: Not applicable
data.token.descriptionstring

Description of the delivery token.

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

Environments, branches and aliases the token reads.

Default: Not applicable
paramobject

Query parameters for the request.

Default: undefined (sends no query parameters)
param.create_with_preview_tokenboolean

Creates a preview token with the delivery token.

Default: API default

Returns: Promise<DeliveryToken>. The new delivery token.

Validation

  • There is no client-side validation. create sends data unchanged as the body.
  • create exists only on stack.deliveryToken(). On stack.deliveryToken('<TOKEN_UID>') 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 Create delivery token request (POST /stacks/delivery_tokens) with the object's headers, data as the body, and every key of param as a query parameter.
  • Each item of data.token.scope names a module and an acl, with the matching list:
    • module: 'environment' with environments, the names of the publishing environments.
    • module: 'branch' with branches, the branch UIDs.
    • module: 'branch_alias' with branch_aliases, the alias UIDs.
  • The API reference recommends one publishing environment per delivery token.
  • Resolves to a new DeliveryToken in the UID form, which the SDK builds from the token key of the response. Call previewToken on it to manage its preview token.

Example

Basic usage: create a token for one environment and the main branch

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

try {
  const deliveryToken = await stack.deliveryToken().create({
    token: {
      name: 'docs-test-delivery-token',
      scope: [
        { module: 'environment', environments: ['<ENVIRONMENT>'], acl: { read: true } },
        { module: 'branch', branches: ['main'], acl: { read: true } }
      ]
    }
  })
  console.log(deliveryToken.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 a description, an alias scope and a preview token

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

try {
  const deliveryToken = await stack.deliveryToken().create(
    {
      token: {
        name: 'docs-test-preview-delivery-token',
        description: 'Read-only token for the website',
        scope: [
          { module: 'environment', environments: ['<ENVIRONMENT>'], acl: { read: true } },
          { module: 'branch_alias', branch_aliases: ['<ALIAS_UID>'], acl: { read: true } }
        ]
      }
    },
    { create_with_preview_token: true }
  )
  console.log(deliveryToken.uid, deliveryToken.preview_token)
} catch (error) {
  console.error(error.errorMessage)
}

delete

delete permanently deletes one delivery token.

NameTypeDescription
paramAnyProperty

Query parameters for the request.

Default: {} (sends no query parameters)
param.forceboolean

Forces the deletion of the delivery token.

Default: API default

Returns: Promise<Response>. The API response with a notice.

Warning Every app that reads content with this token loses access when you delete it. You cannot restore the token. Create a new one and update the apps with its value.

Validation

  • There is no client-side validation.
  • delete exists only on stack.deliveryToken('<TOKEN_UID>') and on the objects that fetch, create and query return. On stack.deliveryToken() 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 delivery token request (DELETE /stacks/delivery_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 delivery 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.deliveryToken('<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)
}

All parameters: force the deletion

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

try {
  const response = await stack.deliveryToken('<TOKEN_UID>').delete({ force: true })
  console.log(response.notice)
} catch (error) {
  console.error(error.errorMessage)
}

fetch

fetch retrieves the details of one delivery token, such as its name and scope.

NameTypeDescription
paramAnyProperty

Query parameters for the request. The API lists none.

Default: {} (sends no query parameters)

Returns: Promise<DeliveryToken>. The requested delivery token.

Validation

  • There is no client-side validation.
  • fetch exists only on stack.deliveryToken('<TOKEN_UID>'). On stack.deliveryToken() 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 delivery token request (GET /stacks/delivery_tokens/{token_uid}) with the object's headers, and every key of param as a query parameter.
  • Resolves to a new DeliveryToken, which the SDK builds from the token key of the response. The properties of the token, such as name and scope, are properties of the new object.

Example

Basic usage: fetch one delivery token

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

try {
  const deliveryToken = await stack.deliveryToken('<TOKEN_UID>').fetch()
  console.log(deliveryToken.name, deliveryToken.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 deliveryToken = await stack.deliveryToken('<TOKEN_UID>').fetch({})
  console.log(deliveryToken.name)
} catch (error) {
  console.error(error.errorMessage)
}

previewToken

previewToken creates a PreviewToken object for the preview token of this delivery token.

This method takes no parameters.

Returns: PreviewToken. A new preview token object.

Validation

  • There is no client-side validation.
  • previewToken exists only on stack.deliveryToken('<TOKEN_UID>') and on the objects that fetch, create and query return. On stack.deliveryToken() 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. previewToken sends no request.
  • The new object holds the delivery token UID, and its requests go to /stacks/delivery_tokens/{token_uid}/preview_token. It has create and delete.
  • The new object shares the header map of this delivery token object.

Example

Basic usage: create the preview token of a delivery 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.deliveryToken('<TOKEN_UID>').previewToken().create()
  console.log(result.preview_token)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

query

query builds a query for the delivery tokens of the stack.

NameTypeDescription
paramsobject

Query parameters for the request. The API lists none.

Default: {}

Returns: Query. A query for delivery tokens, sent when you call find(), findOne() or count().

Validation

  • There is no client-side validation.
  • query exists only on stack.deliveryToken(). On stack.deliveryToken('<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 delivery tokens request (GET /stacks/delivery_tokens).
  • query copies the object's headers when you call it. A header you add to the delivery token object later does not reach the query.
  • Each item in the items array of the find result is a DeliveryToken in the UID form, with methods such as fetch and delete.

Example

Basic usage: list the name of each delivery 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.deliveryToken().query().find()
  result.items.forEach((deliveryToken) => console.log(deliveryToken.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.deliveryToken().query({}).find()
  console.log(result.items.length)
} catch (error) {
  console.error(error.errorMessage)
}

removeHeader

removeHeader removes one request header from the delivery token object, for every request it sends afterwards.

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

Returns: DeliveryToken. The same delivery 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 delivery token object's header map and sends no request.
  • Until its first header change, the delivery 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, and the PreviewToken object from previewToken(). 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 delivery token

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

const deliveryToken = stack.deliveryToken('<TOKEN_UID>')
  .addHeader('x-request-id', 'docs-123')
  .removeHeader('x-request-id')
console.log(deliveryToken.stackHeaders)

update

update saves the name, description and scope that you set on the delivery token object.

NameTypeDescription
paramAnyProperty

Query parameters for the request. The API lists none.

Default: {} (sends no query parameters)

Returns: Promise<DeliveryToken>. The updated delivery token.

Validation

  • There is no client-side validation.
  • update exists only on stack.deliveryToken('<TOKEN_UID>') and on the objects that fetch, create and query return. On stack.deliveryToken() 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 delivery token request (PUT /stacks/delivery_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 scope uses the same shape as in create: environment, branch and branch_alias modules, each with its list and an acl.
  • Resolves to a new DeliveryToken, which the SDK builds from the response.

Example

Basic usage: rename a delivery token

import contentstack from '@contentstack/management'

const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })

try {
  const deliveryToken = await stack.deliveryToken('<TOKEN_UID>').fetch()
  deliveryToken.name = 'Website production token'
  deliveryToken.description = 'Read-only token for the production website'
  const updatedToken = await deliveryToken.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 scope 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 deliveryToken = await stack.deliveryToken('<TOKEN_UID>').fetch()
  deliveryToken.scope = [
    { module: 'environment', environments: ['<ENVIRONMENT>'], acl: { read: true } },
    { module: 'branch', branches: ['main', '<BRANCH>'], acl: { read: true } }
  ]
  const updatedToken = await deliveryToken.update({})
  console.log(updatedToken.scope)
} catch (error) {
  console.error(error.errorMessage)
}