Management SDK - Intro

Managing content from outside of the CMS has never been easier. The Content Management JS SDK allows developers to create/update, or apply workflow actions to content using our Content Management API.

Use Cases

  • Importing Content
  • Implementing custom Approval Workflows
  • Keeping content in-sync with other systems
  • Updating content lists
  • Publishing pages

Using the SDK with NPM (Node Package Manager)

Install the Agility Content Management JS SDK package into your project:

> npm install @agility/management-sdk

Authentication

Before using the SDK, you must authenticate against the Agility Management API to obtain a valid access token. This token is required for all subsequent API requests.

The authentication process uses OAuth 2.0 and requires multiple steps:

First, initiate the authorization flow by making a GET request to the authorization endpoint: 

const authUrl = 'https://mgmt.aglty.io/oauth/authorize';

//if you want to get a refresh token and use the SDK offline, use this authorization URL:
//const authUrl = 'https://mgmt.aglty.io/oauth/authorize?scope=offline_access';

const params = new URLSearchParams({
  response_type: 'code',
  redirect_uri: 'YOUR_REDIRECT_URI',
  state: 'YOUR_STATE',
  scope: 'openid profile email offline_access'
});

// Redirect the user to the authorization URL
window.location.href = `${authUrl}?${params.toString()}`;

After successful authentication, you'll receive an authorization code at your redirect URI. Use this code to obtain an access token: 

const response = await fetch('https://mgmt.aglty.io/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    code: 'YOUR_AUTHORIZATION_CODE'
  })
});

const { access_token, refresh_token, expires_in } = await response.json();

Use the obtained token to initialize the SDK: 

import * as mgmtApi from "@agility/management-sdk";

// Initialize the Options Class with your authentication token
let options = new mgmtApi.Options();
options.token = access_token; // Use the token obtained from authentication

// Initialize the APIClient Class
let apiClient = new mgmtApi.ApiClient(options);

let guid = "<<Provide the Guid of the Website>>";
let locale = "<<Provide the locale of the Website>>"; // Example: en-us

// Now you can make authenticated requests
var contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);
console.log(JSON.stringify(contentItem));

When the access token expires, use the refresh token to obtain a new access token: 

const response = await fetch('https://mgmt.aglty.io/oauth/refresh', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    refresh_token: 'YOUR_REFRESH_TOKEN'
  })
});

const { access_token, refresh_token, expires_in } = await response.json();

Note:

  • The access token has a limited lifetime of 24 hours. When your token expires, subsequent requests to the API will result in a `401 Unauthorized` response.
  • The refresh token can be used to obtain new access tokens, but ONLY if you authorized with the offline_access scope (https://mgmt.aglty.io/oauth/authorize?scope=offline_access). The refresh token is valid for 30 days.
  • Store tokens and refresh tokens securely and never expose them in client-side code.
  • Implement proper error handling for authentication failures.

Personal Access Tokens (PAT)

For automation, CI/CD pipelines, and server-side workflows where an OAuth redirect isn't practical, use a Personal Access Token (PAT) instead.

Generating a PAT

PATs are created via the Management API. First authenticate with OAuth (see above), then call POST /api/v1/tokens/create via Swagger. Swagger URLs by region:

-u    → https://mgmt.aglty.io/swagger
-us2  → https://mgmt-usa2.aglty.io/swagger
-c    → https://mgmt-ca.aglty.io/swagger
-e    → https://mgmt-eu.aglty.io/swagger
-a    → https://mgmt-aus.aglty.io/swagger
-d    → https://mgmt-dev.aglty.io/swagger

Request body:

POST /api/v1/tokens/create
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH_TOKEN

{
  "name": "my-automation-token",
  "expiryDate": "2028-01-01T00:00:00Z"
}

Note: expiryDate is required and must be a future date. The token value is returned once in the response — save it immediately.

Using a PAT with the SDK

Initialization is identical to OAuth — pass the PAT directly as token:

import * as mgmtApi from "@agility/management-sdk";

let options = new mgmtApi.Options();
options.token = "<<your-personal-access-token>>";

let apiClient = new mgmtApi.ApiClient(options);

PAT Restrictions

PATs have full access to content operations but cannot access user management, token management, or admin-level endpoints — these return 403 Forbidden.

SDK Functions

The following are a collection of SDK functions and their response schemas. 

See more details in the readme here: https://github.com/agility/agility-cms-management-sdk-typescript

API Client

Everything starts with establishing an API client. 

import * as mgmtApi from "@agility/management-sdk";

//initialize the Options Class
let options = new mgmtApi.Options();

options.token = "<<Provide Auth Token>>"
//Initialize the APIClient Class
let apiClient = new mgmtApi.ApiClient(options);

let guid = "<<Provide the Guid of the Website>>";
let locale = "<<Provide the locale of the Website>>"; //Example: en-us

//make the request: get a content item with the ID '22'
var contentItem = await apiClient.contentMethods.getContentItem(22, guid, locale);

//To log the response of the contentItem object in console.
console.log(JSON.stringify(contentItem));

Options Fields

Options {
    token: string;
    baseUrl: string | null;
    refresh_token: string;
    duration: number | 3000;
    retryCount: number | 500;
}

SDK Operations

View it on GitHub

The source code for the SDK is open source on GitHub and available for you to work with, create issues, and fork: https://github.com/agility/agility-cms-management-sdk-typescript