DeliveryToken
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 Name | Returns | Description |
|---|---|---|
| query | A query for delivery tokens, sent when you call find(), findOne() or count(). | Lists the delivery tokens of the stack. |
| create | The new delivery token. | Creates a delivery token. |
Work with one delivery token. Available on stack.deliveryToken('<TOKEN_UID>').
| Method Name | Returns | Description |
|---|---|---|
| fetch | The requested delivery token. | Fetches the details of one delivery token. |
| update | The updated delivery token. | Saves a new name, description or scope. |
| delete | The API response with a notice. | Deletes a delivery token. |
| previewToken | A new preview token object. | Opens the preview token of the delivery token. |
Set headers. Available on both forms.
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same delivery token, for chaining. | Adds one header to the object. |
| addHeaderDict | The same delivery token, for chaining. | Adds several headers to the object. |
| removeHeader | The 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.
| 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: 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.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
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.
| Name | Type | Description |
|---|---|---|
| data (required) | object | Details of the token, under a token key. |
| data.token.name (required) | string | Name of the delivery token. |
| data.token.description | string | Description of the delivery token. |
| data.token.scope (required) | Scope[] | Environments, branches and aliases the token reads. |
| param | object | Query parameters for the request. |
| param.create_with_preview_token | boolean | Creates a preview token with the delivery token. |
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.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. |
| param.force | boolean | Forces the deletion of the delivery token. |
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.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. The API lists none. |
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.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters for the request. The API lists none. |
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.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
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.
| Name | Type | Description |
|---|---|---|
| param | AnyProperty | Query parameters for the request. The API lists none. |
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)
}