Skip to main content
Contentstack MCP profile hub is in general availability!

OAuth and machine-to-machine apps

•
6 min read

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:

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:

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:

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:

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 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.

Frequently asked questions

  • How long are Contentstack OAuth access tokens valid?

    Both app tokens and user tokens are valid for 60 minutes. Authorization codes are valid for 60 seconds.

  • Do I need OAuth for calls made with appSdk.api()?

    No. The host makes those calls with the permissions granted in the UI Locations tab. You need the OAuth tab when your own backend calls Contentstack.

  • Are machine-to-machine apps generally available?

    At the time of writing, Contentstack documents machine-to-machine apps as a beta that your account manager enables. Standard apps with app tokens cover most server-to-server needs.