---
title: "Build your first Developer Hub app"
url: "https://developers.contentstack.com/guides/build-your-first-developer-hub-app"
type: "guide"
level: "intermediate"
intent: "build"
outcome: "You can build, install, secure and host a Developer Hub app that renders in several UI locations and calls Contentstack and third-party APIs."
prerequisites:
  - "A Contentstack organization where you can create apps in Developer Hub"
  - "A stack you can install a test app into"
  - "Node.js 22 or later and working knowledge of React and TypeScript"
tags:
  - "sdk"
  - "api"
  - "security"
  - "react"
authors:
  - "Tim Benniks"
published: "2026-11-28T09:00:00.000Z"
updated: "2026-11-15T10:55:43.491Z"
---

# Build your first Developer Hub app

- **Authors:** Tim Benniks
- **Published:** 2026-11-28T09:00:00.000Z
- **Updated:** 2026-11-15T10:55:43.491Z
- **Level:** Intermediate
- **Intent:** Build
- **Tags:** sdk, api, security, react
- **Chapters:** 4
- **Source:** [https://developers.contentstack.com/guides/build-your-first-developer-hub-app](https://developers.contentstack.com/guides/build-your-first-developer-hub-app)

---

## Table of Contents

1. [Manifest and UI locations](#manifest-and-ui-locations)
2. [App SDK v2 essentials](#app-sdk-v2-essentials)
3. [OAuth and machine-to-machine apps](#oauth-and-machine-to-machine-apps)
4. [Hosting and going live](#hosting-and-going-live)

A Developer Hub app is how you put your own UI inside Contentstack. It can be a custom field, a sidebar next to the entry editor, a dashboard widget, or a full page, and it ships as one web app that Contentstack loads into iframes. If you have built a Contentful app or a Shopify app before, the model will feel familiar: a manifest declares where the app shows up and what it may do, and an SDK connects your code to the host.

This guide takes you from an empty folder to an installed app that reads and writes entry data, stores configuration per installation, calls APIs without exposing tokens, and runs on a production URL. Each chapter covers one layer of the stack, so you can also jump to the one you need.

## What you'll learn

- How an app, its manifest and its UI locations fit together


- How to scaffold an app with the csdx app:create command


- How to initialize App SDK v2 and use location-specific APIs


- How installation configuration and secrets are stored


- How app tokens, user tokens and the proxy differ


- How to host the app, subscribe to lifecycle webhooks, and go live



## How the pieces fit

Contentstack concept: An app is a manifest plus hosted code. The manifest lives in Developer Hub. The code lives wherever you host it.

When an editor opens an entry that uses your custom field, Contentstack reads the installed manifest, builds the iframe URL from your hosting URL plus the location's path, and loads your app. Your code calls ContentstackAppSDK.init() and gets back an object that knows which location it is running in, which entry is open, and which installation configuration applies.

flowchart LR  A[Developer Hub manifest] -->|UI locations, OAuth, webhooks, hosting| B[Installation in a stack]  B --> C[Contentstack UI]  C -->|iframe: hosting URL + path| D[Your app]  D -->|App SDK: init, field, entry, api| C  C -->|proxied requests| E[Contentstack APIs]  C -->|rewrites + mappings| F[Third-party APIs]The diagram shows the two directions that matter. Configuration flows down from the manifest into each installation. Requests flow up from your app through the host, which adds credentials so your frontend never holds a token.

## How the chapters fit together

- [Manifest and UI locations](/guides/build-your-first-developer-hub-app/manifest-and-ui-locations) creates the app, explains the manifest, and helps you pick locations.


- [App SDK v2 essentials](/guides/build-your-first-developer-hub-app/app-sdk-v2-essentials) initializes the SDK and reads and writes field, entry and installation data.


- [OAuth and machine-to-machine apps](/guides/build-your-first-developer-hub-app/oauth-and-machine-to-machine-apps) covers app tokens, user tokens, scopes and the proxy patterns.


- [Hosting and going live](/guides/build-your-first-developer-hub-app/hosting-and-going-live) moves the app off localhost, adds lifecycle webhooks, and walks through a go-live checklist.



Read them in order the first time. Chapter 2 assumes the scaffold from chapter 1, and chapter 4 assumes the secrets setup from chapter 3.

## Key takeaways

- An app is a manifest in Developer Hub plus a single-page app you host.


- UI locations are iframes. The location's path is appended to your hosting URL.


- The App SDK is the only channel between your code and Contentstack.


- API calls go through the host, so your frontend never stores a token.



When you hit problems after launch, [five Developer Hub gotchas that bite on day two](/blog/five-developer-hub-gotchas-that-bite-on-day-two) covers the ones that show up most often.



---

## Manifest and UI locations

Every Developer Hub app starts with two things: an entry in Developer Hub that holds the manifest, and a code base that renders each location. You can create both by hand in the Developer Hub UI, but the apps CLI plugin does it in one command and gives you a working React boilerplate.

This chapter sets up that scaffold and explains what the manifest controls, so the rest of the guide has something real to build on.

## What you'll learn

- How to scaffold an app with csdx app:create


- What the app manifest contains


- Which UI locations exist and what each one is for


- How location paths map to routes in your app


- How to run the app locally inside Contentstack



## Scaffold the app with the CLI

The apps CLI is an opt-in plugin for the Contentstack CLI. Install it once:

```bash
csdx plugins:install @contentstack/apps-cli
csdx auth:login
```

The plugin uses your login session. Management tokens do not work here, so log in first.

Now create the app:

```bash
csdx app:create --name seo-helper --app-type stack
```

The command asks which boilerplate to use (App Boilerplate, DAM App Boilerplate or Ecommerce App Boilerplate), registers the app in Developer Hub, downloads the boilerplate into a folder named after the app, writes a manifest.json into it, and runs npm install. App names are 3 to 20 characters and unique within an organization.

Pick App Boilerplate for this guide. It is React, TypeScript and Vite with every stack location already wired up.

If you skip the GitHub download prompt, the app is still registered but no local manifest.json is written. Run the command again or create the folder from the [boilerplate repository](https://github.com/contentstack/marketplace-app-boilerplate).

## Understand the manifest

Contentstack concept: The app manifest is the declarative definition of your app. It holds identity, UI locations, OAuth settings, webhooks, hosting and Advanced Settings.

You edit most of it through the tabs in Developer Hub. The App Manifest tab shows the JSON, and you can export or edit it there. The ui_location part looks like this:

```json
{
  "ui_location": {
    "signed": true,
    "base_url": "http://localhost:3000",
    "locations": [
      {
        "type": "cs.cm.stack.custom_field",
        "meta": [
          {
            "name": "SEO score",
            "path": "/custom-field",
            "data_type": "json",
            "signed": true,
            "enabled": true
          }
        ]
      },
      {
        "type": "cs.cm.stack.sidebar",
        "meta": [
          { "name": "SEO checks", "path": "/entry-sidebar", "signed": true }
        ]
      },
      {
        "type": "cs.cm.stack.config",
        "meta": [{ "path": "/app-configuration", "signed": true }]
      }
    ]
  }
}
```

A few fields carry most of the weight:

- type is the location identifier. There is one entry per type.


- path is appended to the hosting URL to build the iframe src.


- signed makes Contentstack add a short-lived JWT to the iframe URL, which [chapter 4](/guides/build-your-first-developer-hub-app/hosting-and-going-live) shows you how to verify. Set it on each meta entry, not only at the top level.


- data_type is required for custom fields. It decides what kind of value the field stores: text, number, isodate, boolean, json, reference, file or asset.



base_url is overwritten by the URL you set in the Hosting tab, so treat the Hosting tab as the source of truth.

## Choose your UI locations

A UI location is an extension point in the Contentstack UI. Each one renders your app in an iframe, except JSON RTE plugins, which load as a script inside the editor.

Location

Manifest type

Use it for

App configuration

cs.cm.stack.config

Settings and API keys per installation

Custom field

cs.cm.stack.custom_field

A field type in a content type, such as a product picker

Entry sidebar

cs.cm.stack.sidebar

Tools that act on the open entry, such as SEO checks

Stack dashboard

cs.cm.stack.dashboard

A widget on the stack dashboard

Asset sidebar

cs.cm.stack.asset_sidebar

Tools for the open asset, such as image metadata

Full page

cs.cm.stack.full_page

A standalone screen inside the stack

Field modifier

cs.cm.stack.field_modifier

Acting on an existing field in the entry editor

JSON RTE

cs.cm.stack.rte

Buttons and plugins in the JSON Rich Text Editor

Organization config

cs.org.config

Settings for an organization app

Organization apps can use only cs.org.config and the organization-level full page. Everything else needs a stack app.

Start small. Declare only the locations you build. The boilerplate wires up all of them, and every unused location is one more screen that installers see and one more route you have to keep working. A first app usually needs a config page plus one location where editors do the work.

## Map paths to routes

The boilerplate is one single-page app with a route per location: /custom-field, /entry-sidebar, /app-configuration, /stack-dashboard, /asset-sidebar, /full-page, /field-modifier and more. Each route is lazy-loaded, so a sidebar does not download the custom field code.

When you remove a location from the manifest, remove its route as well. When you add one, make sure the path matches a route exactly. A mismatch loads your app's 404 inside the Contentstack UI, which is easy to miss if you only test one location.

## Run it inside Contentstack

Start the dev server:

```bash
npm run dev
```

The boilerplate serves on http://localhost:3000. In Developer Hub, open your app, go to the Hosting tab, pick Custom Hosting and enter that URL. Then click Install App, pick a test stack, and open an entry. Your locations now render from your machine, and code changes hot-reload.

Use a tunnel such as ngrok if someone else needs to see the app from their own browser.

## Where people get confused

Code changes and manifest changes behave differently. Code at your hosting URL updates for every installation as soon as you deploy it. Manifest changes, such as a new location or a new webhook event, create a new version. Existing installations see that version as an available update. They do not switch over on their own.

Locations also need permissions. The UI Locations tab has an App Permissions section, and by default no permissions are selected. If your app calls Contentstack APIs, grant only the scopes those calls need. [Chapter 3](/guides/build-your-first-developer-hub-app/oauth-and-machine-to-machine-apps) covers scopes in detail.

## Key takeaways

- Run csdx plugins:install @contentstack/apps-cli, then csdx app:create to register an app and scaffold the boilerplate in one step.


- The manifest declares locations, OAuth, webhooks, hosting and Advanced Settings.


- Each location's path is appended to the hosting URL. Keep paths and routes in sync.


- Set signed: true on each meta entry that handles data.


- Declare only the locations you build, and remember that manifest changes become updates for existing installations.





---

## App SDK v2 essentials

The App SDK is the only way your app talks to Contentstack. It tells you where you are running, gives you the open entry or field, proxies API calls, and stores configuration per installation. Version 2 is the current major line, and @contentstack/app-sdk 2.4.1 is the latest release at the time of writing.

This chapter covers the calls you will use in almost every app.

## What you'll learn

- How to initialize the SDK once and share it


- How to tell which location your code is running in


- How to read and write field and entry data


- How to size the iframe


- How installation data and secrets are stored


- How to call Contentstack APIs through the SDK



## Initialize once

Install the package if you did not start from the boilerplate:

```bash
npm install @contentstack/app-sdk
```

Then initialize it:

```typescript
import ContentstackAppSDK from "@contentstack/app-sdk";

const appSdk = await ContentstackAppSDK.init();
```

init() does a handshake with the parent frame and returns a UiLocation object. The call is memoized, so calling it again returns the same instance. In React, call it in one provider and share the result through context. The boilerplate does this in MarketplaceAppProvider and exposes a useAppSdk() hook.

Handle rejection. init() rejects when the page has no parent window, and times out after 10 seconds when the parent never answers. Render an error state instead of a blank screen:

```typescript
ContentstackAppSDK.init()
  .then((sdk) => setAppSdk(sdk))
  .catch(() => setFailed(true));
```

## Know where you are

Contentstack concept: appSdk.location holds one object per location type. Only the object for the current location is set. The others are null.

```typescript
const location = appSdk.getCurrentLocation();

if (location === "FIELD") {
  const customField = appSdk.location.CustomField;
  // customField.field, customField.entry, customField.frame
}

if (location === "WIDGET") {
  const sidebar = appSdk.location.SidebarWidget;
  // sidebar.entry, sidebar.stack
}
```

The values come from the SDK's LocationType enum: APP_CONFIG_WIDGET, FIELD, WIDGET (entry sidebar), DASHBOARD, ASSET_SIDEBAR_WIDGET, FULL_PAGE_LOCATION, FIELD_MODIFIER_LOCATION, CONTENT_TYPE_SIDEBAR_WIDGET, GLOBAL_FULL_PAGE_LOCATION and RTE. If you are coming from v1, note that v2 renamed EntryFieldLocation to FieldModifierLocation and FullscreenAppWidget to FullPage.

You also get identifiers you will need later: appSdk.ids contains apiKey, appUID, installationUID, locationUID, orgUID and userUID.

## Read and write field data

A custom field reads its current value with getData() and writes with setData():

```typescript
const field = appSdk.location.CustomField?.field;

const current = field?.getData() ?? {};

await field?.setData({ ...current, score: 82, checkedAt: new Date().toISOString() });
```

setData() updates the value in the editor. The entry still has to be saved before the value is stored. The shape must match the field's data_type from the manifest. A json field takes an object, a text field takes a string.

From 2.4.0, setData() throws a ValidationError when the host rejects the value. Wrap writes in try/catch, and subscribe to field.onError() for errors that happen after the write is applied.

## React to the entry

The entry is available in custom fields, entry sidebars and field modifiers:

```typescript
const entry = appSdk.location.SidebarWidget?.entry;

const saved = entry?.getData();
const draft = await entry?.getDraftData();

entry?.onChange((data) => runChecks(data));
entry?.onSave((data) => runChecks(data));
```

getData() returns the saved entry. getDraftData() returns what the editor has not saved yet. Use onChange for live feedback and onSave for anything expensive. Subscribe to events instead of polling the entry on a timer.

## Size the frame

Custom field and dashboard frames do not resize themselves by default. If your field grows, the editor sees a scrollbar or a clipped UI. Turn on auto-resizing, or set a height yourself:

```typescript
const frame = appSdk.location.CustomField?.frame;

frame?.enableAutoResizing();
// or a fixed height
await frame?.updateHeight(320);
```

## Store installation data

Contentstack concept: Each installation has two configuration buckets. configuration is readable by your app in every location. serverConfiguration is encrypted, never sent to a UI location, and only read by the proxy and your own backend.

The app configuration location reads and writes both:

```typescript
const installation = appSdk.location.AppConfigWidget?.installation;

const data = await installation?.getInstallationData();

const payload: Record<string, unknown> = {
  configuration: { ...data?.configuration, region: "eu", hasApiKey: true },
};

// Only send serverConfiguration when the user typed a new key.
if (apiKeyInput) {
  payload.serverConfiguration = { apiKey: apiKeyInput };
}

await installation?.setInstallationData(payload as any);

installation?.setValidity(Boolean(apiKeyInput || data?.configuration.hasApiKey), {
  message: "Add an API key",
});
```

setValidity(false) blocks the Save button on the config screen, with an optional message. The SDK types mark both buckets as required, hence the cast: leaving serverConfiguration out is what keeps a stored key in place.

Two rules keep this safe:

- Secrets go in serverConfiguration, never in configuration. Put a non-secret flag such as hasApiKey: true in configuration so other locations can check that a key exists.


- Each bucket you send replaces what is stored. Sending serverConfiguration: {} wipes the saved secret. Only send serverConfiguration when the user sets or clears a secret, and send one full snapshot per change instead of one call per keystroke.



## Call Contentstack APIs

appSdk.api() is a fetch-style call that the host executes with the app's granted permissions:

```typescript
const res = await appSdk.api(`${appSdk.endpoints.CMA}/v3/content_types`, {
  method: "GET",
});

if (!res.ok) {
  throw new Error(`Request failed with ${res.status}`);
}

const { content_types } = await res.json();
```

api() resolves on HTTP errors. A 401 or 404 comes back as a Response, and a transport failure becomes a Response with status 500. Always check res.ok. Log appSdk.endpoints once in your app to confirm the base URL for your region.

For heavier work, pass the SDK's adapter to the Management SDK so every request goes through the host:

```typescript
import { client } from "@contentstack/management";

const cma = client({ adapter: appSdk.createAdapter() });
```

The SDK also exposes appSdk.stack with helpers such as getContentTypes(), getEnvironments() and search().

## Where people get confused

appSdk.store looks like a place for settings, but it is per location and backed by browser storage. Use installation data for anything that must survive across users and browsers.

The app config location only exists while someone is configuring the app. Other locations read configuration with appSdk.getConfig(), not with getInstallationData().

## Key takeaways

- Call ContentstackAppSDK.init() once, share it through context, and handle rejection.


- Branch on appSdk.getCurrentLocation(). Only the matching appSdk.location.* object is set.


- field.setData() is saved with the entry and throws ValidationError on rejection from 2.4.0.


- Call frame.enableAutoResizing() in custom fields that change height.


- Keep secrets in serverConfiguration, and never send it as {} unless you mean to delete it.


- Check res.ok after appSdk.api(). It does not throw on HTTP errors.



Next, [OAuth and machine-to-machine apps](/guides/build-your-first-developer-hub-app/oauth-and-machine-to-machine-apps) explains which token your calls use and how to reach third-party APIs.



---

## OAuth and machine-to-machine apps

Your app can call APIs from three places: the browser through the App SDK, your own backend with an OAuth token, or a third-party service through the Contentstack proxy. Each one uses a different credential, and mixing them up is how apps end up with tokens in client code or permissions that are far too broad.

This chapter explains which token goes where and how to keep secrets on the server.

## What you'll learn

- The difference between app tokens and user tokens


- How the OAuth authorization code flow works for Contentstack apps


- How scopes are named and how to keep them small


- How to call third-party APIs with Advanced Settings


- Where machine-to-machine apps fit



## Start with the call that needs no token

Contentstack concept: UI location permissions are scopes the host uses when your app calls appSdk.api() or the Management SDK through appSdk.createAdapter().

You grant them in the UI Locations tab under App Permissions. Nothing is selected by default. Installers see the list and approve it when they install.

This path needs no token handling in your code at all. If your app only works inside the Contentstack UI, start here and stop here.

## App tokens and user tokens

You need OAuth when code outside the UI, usually your backend, calls Contentstack. The OAuth tab in Developer Hub offers two token types:


App token

User token

Actions are attributed to

The app installation

The user who authorized the app

Survives the user being removed

Yes

No, revoked with the user

Revoked when

The app is uninstalled

The user or an org admin revokes it under Manage, Authorized Apps

Good for

Server-to-server, long-running jobs

Actions that must show up as a specific person

Both are valid for 60 minutes and are renewed with a refresh token. If you are coming from GitHub Apps, an app token is the installation token and a user token is the user-to-server token.

Pick app tokens for sync jobs, webhook handlers and scheduled work. Pick user tokens when audit logs must show who did something. A few operations, such as creating a Git-based Launch project, only accept a user token.

## The authorization code flow

The flow is standard OAuth 2.0. For a user token, send the user to:

```bash
https://app.contentstack.com/apps/{app_uid}/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}&state={state}
```

For an app token, send the installer to https://app.contentstack.com/apps/{app_uid}/install.

Contentstack redirects back to your redirect URI with a code and a location parameter such as NA or EU. The code is valid for 60 seconds, so exchange it right away on your server:

```typescript
const res = await fetch("https://app.contentstack.com/apps-api/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    client_id: process.env.CS_CLIENT_ID!,
    client_secret: process.env.CS_CLIENT_SECRET!,
    redirect_uri: process.env.CS_REDIRECT_URI!,
    code,
  }),
});

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

Refresh with the same endpoint and grant_type=refresh_token, passing refresh_token instead of code. Then call the Content Management API with Authorization: Bearer <access_token>.

Use the location value to pick the base URL. EU is https://eu-app.contentstack.com, and Azure and GCP regions have their own hosts. A private app only authorizes members of your own organization, and cross-region installs need a public or public unlisted app.

To check a token without spending an API call, POST /apps-api/introspect with the token returns "active": true and its scopes, or only "active": false.

## Keep scopes small

Scopes follow a resource.action:permission pattern, such as cm.entries.management:read. Reads and writes are separate scopes. Request the ones your code calls and nothing more. Every extra scope is something an installer has to approve and something an attacker gets if your client secret leaks.

The client ID is safe to share. The client secret belongs on the server only: never in the frontend bundle, never in a VITE_* environment variable, never in a repository.

## Call third-party APIs through the proxy

Most apps need a third-party key, such as a translation or SEO API. You do not need a backend for that. Advanced Settings in Developer Hub has three parts:

- Variables hold developer-level values, referenced as {{var.NAME}}.


- Mappings point a name at a path inside the installation's serverConfiguration, referenced as {{map.NAME}}.


- Rewrites map a short source path in your app to an external HTTPS destination.



Say the config page stores serverConfiguration: { seoApi: { key: "..." } }. Create a mapping named SEO_KEY with the value seoApi.key, and a rewrite with source /seo/:endpoint and destination https://api.seo-vendor.example/v1/:endpoint. Then call it from any location:

```typescript
const res = await appSdk.api("/seo/analyze", {
  method: "POST",
  headers: {
    Authorization: "Bearer {{map.SEO_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: pageUrl }),
});
```

The proxy replaces {{map.SEO_KEY}} on the server before the request leaves Contentstack. The key never reaches the browser.

## Where people get confused

The mapping value is a path inside serverConfiguration. Write seoApi.key, not server_configuration.seoApi.key. A wrong path does not fail on save. The placeholder is sent upstream as literal text, and you get a 401 from the vendor.

Rewrites use path patterns, so every :word in a destination is treated as a placeholder. A URL with a colon in it, such as Google's /models/gemini-2.5-flash:generateContent, fails validation. Use one parameter that carries the whole tail, for example source /gemini/:target and destination https://generativelanguage.googleapis.com/v1beta/models/:target, then call /gemini/gemini-2.5-flash:generateContent.

Test every rewrite and mapping from the app on a real installation with a real stored value. Saving them only proves they validate.

## Machine-to-machine apps

A machine-to-machine (M2M) app is an OAuth-only app with no UI locations. It gets an app token with the client_credentials grant, so no user interaction is involved:

```bash
curl -X POST https://app.contentstack.com/apps-api/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$CS_CLIENT_ID&client_secret=$CS_CLIENT_SECRET"
```

At the time of writing, Contentstack documents M2M apps as a beta that your account manager enables. Check the [machine-to-machine apps documentation](https://www.contentstack.com/docs/developers/developer-hub/machine-to-machine-apps) for the current status before you design around them. Until then, a standard app with an app token is the supported way to run server-to-server work.

## Key takeaways

- Use appSdk.api() with UI location permissions when the call happens inside the Contentstack UI. No token handling needed.


- Use an app token for server-to-server work and a user token when actions must be attributed to a person.


- Exchange the authorization code within 60 seconds and refresh tokens before the 60-minute expiry.


- Request only the scopes you call, and keep the client secret on the server.


- Reach third-party APIs with rewrites plus {{map.NAME}}, and write mapping values without a server_configuration. prefix.





---

## Hosting and going live

Up to now the app has run from localhost:3000. That works for you and nobody else. This chapter moves it to a production URL, adds the security checks that matter once real editors use it, and closes with the checklist to run before you hand the app to anyone.

## What you'll learn

- How to host the app on Launch or on your own infrastructure


- How to deploy with csdx app:deploy


- How to verify signed requests


- How to receive app lifecycle webhooks


- What to check before go-live



## Host on Launch

The Hosting tab in Developer Hub offers two options: Hosting with Launch and Custom Hosting. Launch is the low-overhead default. Connect a GitHub or Bitbucket repository, or upload a ZIP, and Launch builds and serves the app. The Hosting tab shows the deployment status and links to the Launch project.

One setting catches most people. Launch defaults the output directory to ./build, and the Vite boilerplate builds to dist. Set the output directory to ./dist in the Launch project or the deploy succeeds and serves nothing.

You can do the same from the terminal:

```bash
csdx app:deploy --org <org-uid> --app-uid <app-uid> --hosting-type hosting-with-launch --launch-project new
```

With --launch-project new, the command creates a Launch project and connects it to the app. Use existing to pick one you already have. An app connects to one Launch project at a time, and a Launch project to one app. If you want more control over Launch deployments from CI, see [deploy from CI with the Launch CLI and API](/guides/deploy-from-ci-with-the-launch-cli-and-api).

## Host it yourself

Pick Custom Hosting and enter your app URL, or run:

```bash
csdx app:deploy --org <org-uid> --app-uid <app-uid> --hosting-type custom-hosting --app-url https://apps.example.com/seo-helper
```

Any static host works. The one requirement is a single-page app fallback: every location path, such as /entry-sidebar, must serve index.html. The boilerplate ships a vercel.json for Vercel. Other hosts need their own rewrite rule.

Contentstack concept: Changing hosting is a manifest change and creates a new version. Deploying new code to the same URL is not. It is live for every installation the moment your host serves it, so keep a staging app and a production app if you need a safe place to test.

## Verify signed requests

When a location has signed: true, Contentstack appends an app-token query parameter to the iframe URL. The value is a JWT signed with RS256. Its payload includes app_uid, installation_uid, organization_uid, user_uid, region and, for stack apps, stack_api_key.

Verify it before you trust anything the frontend sends to your backend. The public key is served at /.well-known/public-keys.json on the Contentstack app host for your region, for example https://app.contentstack.com/.well-known/public-keys.json, under the signing-key property.

```typescript
import jwt from "jsonwebtoken";

const keys = await fetch("https://app.contentstack.com/.well-known/public-keys.json").then((r) => r.json());

export function verifyAppToken(token: string | null) {
  if (!token) throw new Error("Missing app-token");

  const payload = jwt.verify(token, keys["signing-key"], { algorithms: ["RS256"] }) as {
    installation_uid: string;
    stack_api_key?: string;
  };

  return payload;
}
```

Three rules make this check worth having:

- Fail closed. A missing token on a signed location is an error, not a reason to skip the check.


- Scope data by the token's installation_uid and stack_api_key, never by IDs from the request body.


- Do not use the token as a session. It expires after a few minutes. Verify it once and create your own session from the payload.



Cache the public key, and fetch it from the host for the region your installation runs in.

## Receive lifecycle webhooks

The Webhooks tab subscribes your app to events for every installation, without anyone setting up stack webhooks by hand. Stack apps get App Events and Stack Events. Organization apps get App Events only. App Events cover installs, uninstalls and configuration updates, which is what you need to provision and clean up per-installation state in your backend.

sequenceDiagram  participant E as Editor  participant CS as Contentstack  participant B as Your backend  E->>CS: Install app  CS->>B: POST install event  B->>B: Create tenant for installation_uid  E->>CS: Save configuration  CS->>B: POST update event  E->>CS: Uninstall app  CS->>B: POST uninstall event  B->>B: Delete tenant dataSet a public notification URL (localhost is rejected), add HTTP Basic Auth or custom headers if you want, and pick the events. Add people to notify, because the circuit breaker disables a webhook that keeps failing and emails those addresses. Webhook delivery logs appear on the app configuration screen of each installation.

Verify the signature in the X-Contentstack-Request-Signature header before you act on a payload, as described in [securing your app](https://www.contentstack.com/docs/developers/developer-hub/securing-your-app). Treat the body of an update event as sensitive. Do not log it raw or forward it to other tools.

## Go-live checklist

Run through this list before you share the app beyond your own team.

Manifest and locations

- Every declared location renders on a real installation, and unused boilerplate locations are removed.


- Every path matches a route.


- signed: true is set on each meta entry that handles data.


- App Permissions and OAuth scopes are the minimum your code calls.



Security and configuration

- The app-token is verified on every signed location and on your backend, and a missing token fails.


- Secrets live in serverConfiguration. Nothing secret is in configuration, client environment variables or the build output.


- serverConfiguration is only sent when a secret is set or cleared.


- Every rewrite and mapping was tested from the app with a real stored value.



Hosting

- The Hosting tab points at the production URL, not localhost or a tunnel.


- The Launch output directory is ./dist for a Vite build.


- Every location path serves index.html.



Releases

- You know the current manifest version, and existing installations have been told about updates that add locations or webhooks.


- For a public Marketplace listing, you have the name, icon, descriptions, screenshots, documentation, privacy policy and a test organization ready for review.



## Key takeaways

- Host on Launch with the output directory set to ./dist, or on any static host with a single-page app fallback.


- csdx app:deploy connects hosting from the terminal, for Launch or a custom URL.


- Code deploys are live immediately. Only manifest changes are versioned.


- Verify the app-token JWT with RS256, fail closed, and never use it as a session.


- Use app lifecycle webhooks to provision and clean up per-installation state, and verify their signatures.





---

## Do this with AI

Install the developer-hub-app-architect skill from [Contentstack agent skills](https://github.com/contentstack/contentstack-agent-skills). Then ask your agent:

> I want a custom field that lets editors pick products from our PIM. Recommend the UI locations, token type and hosting setup, and draft the app manifest for me to review.

New to this? [Set up your AI workbench](/guides/set-up-your-ai-workbench-for-contentstack) first.




---

## Frequently asked questions

### What is a Developer Hub app?

A single-page web app you host yourself or on Launch. Contentstack loads it in iframes at the UI locations you declare in the app manifest, and it talks to the host through the App SDK.

### Do I need a backend to build an app?

Not for most apps. The App SDK proxies Contentstack API calls, and Advanced Settings let you call third-party APIs with secrets that never reach the browser.

### Which framework should I use?

Any framework that builds a single-page app works. The official boilerplate uses React, TypeScript and Vite, and this guide follows it.

### Can I keep the app private to my organization?

Yes. Every app starts private and installs right away in your own organization. Publishing to the Marketplace is a separate, optional step.

