PreviewToken

View as Markdown

PreviewToken

A PreviewToken manages the preview token of one delivery token. A preview token lets the Live Preview panel retrieve the details of your website. Preview tokens work only with the rest-preview.contentstack.com endpoint, as the Preview Token Collection reference states.

Use this class to

  • create a preview token for a delivery token
  • delete the preview token of a delivery token

Instance State

Get a PreviewToken from the previewToken method of a delivery token object that contains a UID, such as stack.deliveryToken('<TOKEN_UID>').previewToken().

  • The object has one form. It always holds the delivery token UID, and both create and delete act on that delivery token's preview token.
  • stack.deliveryToken().previewToken() throws TypeError, because previewToken exists only on a delivery token object with a UID.

Class-Level Notes

Authentication.

  • Both preview token requests of the Content Management API (CMA) require an authtoken and the stack API key. Use contentstack.client({ authtoken: '<AUTHTOKEN>' }), or log in, then open the stack with client.stack({ api_key: '<API_KEY>' }).

Headers.

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.

Capability Matrix

CapabilitySupportedNotes / Alternative
Fetch a preview token with a separate requestNoThe SDK has no fetch for a preview token. Keep the preview_token value from the object that create resolves to
Create the preview token together with the delivery tokenYesPass { create_with_preview_token: true } as the second argument of the DeliveryToken create method

Method Index

Manage the preview token. Available on stack.deliveryToken('<TOKEN_UID>').previewToken().

Method NameReturnsDescription
createThe delivery token details with the new preview token.Creates a preview token for the delivery token.
deleteThe API response with a notice.Deletes the preview token of the delivery token.

Set headers. Available on every PreviewToken.

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

Class-Level Snippet

The snippet below creates a preview token for a delivery token and prints its value.

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

Methods

Each method of the PreviewToken class has its own section below, with its parameters, validation rules, behavior, and examples.

addHeader

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

addHeaderDict

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

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

Returns: PreviewToken. The same preview 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 preview token object's header map and sends no request.
  • Until its first header change, the preview 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 does the object that create resolves to.
  • A key that already exists takes the new value.

Example

Basic usage: add two headers to one preview token

import contentstack from '@contentstack/management'

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

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

create

create creates a preview token for the delivery token that this object holds.

NameTypeDescription
dataobject

Request body. The API lists no body keys.

Default: undefined (sends no body)
paramobject

Query parameters for the request. The API lists none.

Default: undefined (sends no query parameters)

Returns: Promise<PreviewToken>. The delivery token details with the new preview token.

Validation

  • There is no client-side validation.
  • 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 preview token request (POST /stacks/delivery_tokens/{delivery_token_uid}/preview_token) with the object's headers.
  • Resolves to a new PreviewToken, which the SDK builds from the token key of the response. That key holds the details of the delivery token, such as name and scope, with the new token in preview_token.

Example

Basic usage: create a preview token and print its value

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

All parameters: pass an empty body and 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('<TOKEN_UID>').previewToken().create({}, {})
  console.log(result.preview_token)
} catch (error) {
  console.error(error.errorMessage)
}

delete

delete deletes the preview token of the delivery token that this object holds.

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 After delete, the preview token no longer exists, and requests that send it fail. You cannot restore the token. Call create to get a new one, and replace the old value wherever you use it.

Validation

  • There is no client-side validation.
  • 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 preview token request (DELETE /stacks/delivery_tokens/{delivery_token_uid}/preview_token) with the object's headers, and every key of param as a query parameter.
  • The delivery token itself stays. To delete it, use the DeliveryToken delete method.
  • Resolves to the response body, which carries notice.

Example

Basic usage: delete 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 response = await stack.deliveryToken('<TOKEN_UID>').previewToken().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)
}

removeHeader

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

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

Returns: PreviewToken. The same preview 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 preview token object's header map and sends no request.
  • Until its first header change, the preview 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 does the object that create resolves to.
  • 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 preview token

import contentstack from '@contentstack/management'

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

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