Developers

Keys model

Choose the right credential for the browser SDK, CI prerender, and server automation — and lock down which origins may call the API.

Where to get keys

Create and rotate frontend keys in Dashboard → SDK keys. Create management tokens in Dashboard → API tokens. Full Management API docs live in the API reference.

Credential types at a glance

Name	Type	Required	Description
`pk_…`	`PUBLIC`	optional	Browser SDK on production. Subject to allowedOrigins.
`dk_…`	`DEVELOPMENT`	optional	Browser SDK for staging or development. Same origin rules; easy to disable separately.
`sk_…`	`SECRET`	optional	Server-only legacy secret. CI/prerender; never embed in the browser.
`mt_…`	`API token`	optional	Management API automation with granular permissions. Header X-Macro-Token.

Frontend SDK keys (`pk_` / `dk_`)

These keys identify your website to the Content API from the browser. Put them in macro.config.js as publicKey.

Prefix pk_. Use on production (and staging if you prefer a single key). Subject to allowedOrigins — production origins must be listed explicitly.

macro.config.js

publicKey: 'pk_xxxxxxxx_xxxxxxxxxxxxxxxxx'

Lifecycle

Keys move active → deprecated → revoked. Rotate before revoke so you can roll out the new key without downtime.

Secret keys (`sk_`) vs API tokens (`mt_`)

Use API tokens (mt_…) for new server automation against /management/* with granular permissions.
Keep secrets in CI/CD env vars (for example MACRO_SECRET_KEY for prerender) — never in committed frontend config.

Don’t

Never put sk_ or mt_ in macro.config.js or any browser bundle.
Do not reuse a frontend key for server write automation.

SECRET keys (`sk_`)

Server-only. Legacy sites may still use them on Content API routes (including build-time prerender). New websites are steered toward API tokens instead; existing sk_ keys remain valid for CI/prerender compatibility.

.env (CI / build)

MACRO_SECRET_KEY=sk_...

API tokens (`mt_`)

Management tokens for server automation. New tokens start with zero permissions until you grant them. Prefer header auth:

bash

curl -H "X-Macro-Token: mt_..." \
  https://api.macrocontent.dev/management/whoami

Presets include read_only, content_automation, data_automation, team_manager, and full_admin. See API tokens and Management API.

allowedOrigins

Frontend keys (PUBLIC / DEVELOPMENT) must present a browser Origin (or Referer) that matches the key’s allowlist. Origin checks are defense-in-depth — they do not replace editor authentication.

Name	Type	Description
`Exact origin`	`string`	e.g. https://www.example.com — must match scheme + host + port
`Port wildcard`	`suffix :*`	e.g. https://staging.example.com:* matches any port on that host
`Subdomain wildcard`	`prefix *.`	e.g. *.example.com matches https://app.example.com

Production origins

On production, list every real customer origin on the PUBLIC key in SDK keys. Prefer a separate DEVELOPMENT key for non-production work instead of widening the production allowlist.

Minimal config checklist

macro.config.js

export const macroConfig = {
  apiBaseUrl: 'https://api.macrocontent.dev',
  websiteId: 'your-website-uuid',
  publicKey: 'pk_...', // or dk_...
  defaultLocale: 'en',
  editorLogin: { shortcut: 'Mod+Shift+M' },
  overlay: { enabled: true, theme: 'dark' },
}

apiBaseUrl — Macro API host for your environment
websiteId — platform website UUID from the Dashboard
publicKey — pk_ or dk_ only
editorLogin.shortcut — defaults to Mod+Shift+M

Keys model

Credential types at a glance

Frontend SDK keys (pk_ / dk_)

Secret keys (sk_) vs API tokens (mt_)

SECRET keys (sk_)