Get Started with JavaScript Management SDK

This guide will help you get started with Contentstack JavaScript Management SDK (that uses Content Management APIs) to manage apps powered by Contentstack. This includes operations such as creating, updating, deleting, and fetching content of your Contentstack account.

Prerequisite

You need Node.js version 22 or above installed to use the Contentstack JavaScript Management SDK.

Installation

To install it via npm:

npm i @contentstack/management

To import the SDK, use one of the following ways:

1. JavaScript ES Modules

   This method provides access to the client function via the default export. It requires "type": "module" in package.json to support ES module usage.

   import contentstack from '@contentstack/management';

2. TypeScript with esModuleInterop

   This method provides access to the client function via the default export. Requires "type": "module" in package.json and "esModuleInterop": true in tsconfig.json.

   import contentstack from '@contentstack/management';

3. TypeScript Namespace Import

   This method functions correctly, regardless of the "esModuleInterop" setting in tsconfig.json, ensuring broad compatibility across module configurations.

   import * as contentstack from '@contentstack/management';

4. TypeScript Destructuring

   Accesses the client function through the default export, enabling streamlined integration in ES module environments.

   import contentstack from '@contentstack/management';
   const { client } = contentstack;

Authentication

To use this SDK, you need to authenticate users. You can do this by using an authtoken, credentials, or a management token (stack-level token). Let's discuss them in detail.

Authtoken

An authtoken is a read-write token used to make authorized CMA requests, and it is a user-specific token.

import * as contentstack from '@contentstack/management'
contentstackClient = contentstack.client({ authtoken: 'AUTHTOKEN' })

Login

The login call allows you to sign in to your Contentstack account and obtain an authentication token (authtoken). Multi-Factor Authentication (MFA) is supported for SDK based logins.

Example:

import * as contentstack from '@contentstack/management'
const client = contentstack.client()


// When user does not have MFA enabled
client.login({ email: <emailid>, password: <password> })
.then(() => {

}))

// When user have MFA enabled
client.login({ email: <emailid>, password: <password>, tfa_token: <2FA_token> })
.then(() => {
}))

import * as contentstack from '@contentstack/management'
const client = contentstack.client()

client.login({ email: <emailid>, password: <password>, mfaSecret: <mfaSecret> })
.then(() => {
}))

Note: The mfaSecret is not passed in the request body—it’s used to generate the OTP dynamically, which is then sent as the tfa_token.

OAuth

Note: This feature requires @contentstack/management version 1.20.0 or later and registered OAuth client credentials.

The JavaScript Management SDK supports OAuth 2.0, enabling secure, token-based access to Contentstack’s Content Management APIs. This integration simplifies authentication by automating token acquisition, refresh, and secure lifecycle management.

With OAuth 2.0, developers can easily implement secure access for both web-based interfaces and command-line tools.

Additional Resource: For more information on the OAuth support in JavaScript Management SDK, refer to Implementing OAuth 2.0 with JavaScript Management SDK documentation.

Key Features

1. Easy SDK initialization: Set up OAuth effortlessly by configuring the SDK with minimal credentials.
2. Automatic token management: The SDK seamlessly handles token acquisition, automatic refresh on expiry, and secure in-memory storage—ensuring uninterrupted authentication.
3. Compatible with both web and CLI applications: The SDK works seamlessly across browser-based apps and command-line tools, supporting multiple secure token storage strategies.
4. Built-in logout functionality: Easily terminate the user sessions with a single method that clears tokens and resets the authentication state.
5. Token revocation support included: Integrated token revocation allows your app to invalidate access upon logout or session expiration.

Management Token

Management tokens are stack-level tokens with no users attached to them.

import * as contentstack from '@contentstack/management'
contentstackClient = contentstack.client()
contentstackClient.stack({ api_key: 'API_KEY', management_token: 'MANAGEMENT_TOKEN' })
.fetch()
.then((stack) => {
    console.log(stack)
})
 

Initialize your SDK

To use the JavaScript CMA SDK, you need to first initialize it.

import * as contentstack from '@contentstack/management'

var contentstackClient = contentstack.client({ authtoken: 'AUTHTOKEN' }) 

Initialization with Management Token and Branch

If you want to initialize SDK in a particular branch use the code given below:

import * as contentstack from '@contentstack/management'
contentstackClient = contentstack.client() 
contentstackClient.stack({ api_key: 'API_KEY', management_token: 'MANAGEMENT_TOKEN', branch_uid: 'BRANCH'})

Initialization with Host Configuration

When using Contentstack, set the host to api.contentstack.io to connect to the North America (NA) region. This ensures the client communicates with the correct API endpoint:

https://api.contentstack.io

Contentstack supports multiple regions, each with a distinct base URL. Using the correct region-specific endpoint ensures optimal performance and compliance with regional data regulations.

For a full list of supported region values and their corresponding base URLs, refer to the Content Management API documentation.

import * as contentstack from '@contentstack/management'
const client = contentstack.client({ host: 'api.contentstack.io' });

Proxy Configuration

Contentstack allows you to define HTTP proxy for your requests with the JavaScript Management SDK. A proxied request allows you to anonymously access public URLs even from within a corporate firewall through a proxy server.

Here is the basic syntax of the proxy settings that you can pass within fetchOptions of the JavaScript Management SDK:

import * as contentstack from '@contentstack/management'
const client = contentstack.client({
 proxy: {
   protocol: 'https',
   host: '127.0.0.1',
   port: 9000,
   auth: {
     username: 'username',
     password: 'password'
   }
 },
})

Fetch Stack Details

To fetch your stack details through the SDK, use the following:

import * as contentstack from '@contentstack/management'
contentstackClient = contentstack.client({ authtoken: 'AUTHTOKEN' })
contentstackClient.stack({ api_key: 'API_KEY' })
.fetch()
.then((stack) => {
    console.log(stack)
})

Create an Entry

You can use the following to create an entry in a specific content type of a stack through the SDK:

import * as contentstack from '@contentstack/management'
contentstackClient = contentstack.client({ authtoken: 'AUTHTOKEN' })

var entry  = {
    title: 'Sample Entry',
    url: '/sampleEntry'
}

contentstackClient.stack({ api_key: 'API_KEY' })
    .contentType('CONTENT_TYPE_UID')
    .entry()
    .create({ entry })
    .then((entry) => {
        console.log(entry)
    })

Upload Assets

Use the following code snippet to upload assets to your stack through the SDK:

import contentstack from '@contentstack/management'
contentstackClient = contentstack.client({ authtoken: 'AUTHTOKEN' })

var asset  = {
    upload: 'path/to/file',
    title: 'Asset Title'
}

contentstackClient.stack({ api_key: 'API_KEY' }).asset().create({ asset })
.then((asset) => {
    console.log(asset)
}) 

Further Reading

• Contentstack Website
• Content Management API Docs