Environments and keys

Every organization’s content lives in environments, and every API call is made with a key bound to one of them. Knowing which environment a key is bound to tells you what that key can see.

Authoring and delivery environments

There are two kinds of environment.

• An authoring environment is a drafting space. Contracts, Templates, Components, folders, the Experience tree and streams all belong to one authoring environment. Content in one authoring environment is invisible from another, as if they were separate organizations. Category groups and categories are the organization’s, shared by every app; which groups an authoring environment uses is chosen per environment, and only those appear on its taxonomy routes.
• A delivery environment holds published content. It is what the Content Delivery API serves, and it holds only what was published into it.

Every organization starts with one of each, and many never need more. Organizations that run a staging and production pipeline typically have several of both, such as a Staging authoring environment publishing to a Staging delivery environment, and a Live authoring environment publishing to Production.

Moving content between environments

Three relationships connect environments. Each one is set up by an administrator in the app, under Configure → Environments.

Publishing goes from an authoring environment to a delivery environment. It copies a snapshot of the content into the delivery environment, where the Delivery API can serve it. Each delivery environment receives publishes from one authoring environment at a time; one authoring environment may publish to several delivery environments. See Publishing.

Promotion copies draft content from one authoring environment into another: a Component or page together with everything it depends on (its Contract, Template, referenced Components and so on), ready to be published there. Promotion moves drafts; it never makes anything live on its own. It is the usual way a change moves from Staging to Live.

Realms are how several brands or sites share content inside one organization. They are not environments. An environment is a stage content passes through; a realm says whose content it is. An organization has one root realm and can add realms below it. A realm reads what it owns and what the realms above it own, with nothing copied and nothing to sync, and it changes only what it owns. A realm exists in every authoring environment, so Staging and Live each show the same brands. Realms are set up in the app, and only on plans that include more than one.

A key acts in one realm, or for a delivery key in a realm and the realms below it. Organizations with only the root realm see no difference, and keys made before realms act in the root realm.

Promotion is done in the app, and a release pipeline can also run it with a deployment key bound to one edge (see Promote content from a pipeline). The Content Management API can’t promote.

A published page keeps being served if the publishing relationship that produced it is later removed. Removing it only stops new publishes and unpublishes between those two environments.

API keys

There are six families of key, each for a different API. All are shown once, when they are created, and only a hash is stored, so a lost key cannot be recovered. Revoke it and create another.

Key	API	Bound to	Created in
Delivery key (server-side or browser-safe)	Content Delivery API	One delivery environment	Content: Settings → API Keys → Delivery keys
Management key	Content Management API	One authoring environment and one role	Content: Settings → API Keys → Management keys
Deployment key	Content Deployment API	One promotion edge (a source and a target authoring environment) and one role	Content: Settings → API Keys → Deployment keys
Forms SDK key	Forms	The organization	Hub: API Keys
Audience management key	Audience Management API	The organization	Audience: Settings → API keys
Audience delivery key (server-side or browser-safe)	Audience Delivery API	The organization	Audience: Settings → Delivery keys

Every key is sent the same way:

Authorization: Bearer <key>

Delivery keys

A delivery key reads published content only. Draft edits never reach it. It is bound to one delivery environment, so to run the same site against development, staging and production, create one key per environment and give each deployment its own key. The site’s code stays the same.

There is one kind of delivery key, and it can be used in two ways.

Server-side (the default) has no restrictions. It works from any origin and any network, so it must stay on a server, in a build step or in an edge function. Never put a server-side key in code that reaches a browser. Use one for server-side rendering, static site generation and back-end integrations.

Browser-safe carries restrictions, turned on with the Browser-safe key switch when you create it (or later, with Manage):

• Allowed origins: the websites the key may be used from, such as https://www.example.com. They are pre-filled from the delivery environment’s site host names. Add http://localhost:<port> for local development. One leading *. label is allowed as a wildcard (https://*.preview.example.com) for per-branch preview deployments.
• Allowed IP ranges: CIDR ranges or single addresses the key may be used from.

A browser-safe key can safely be shipped in a website’s JavaScript. It reads the same published content a visitor to the site can already see, and its restrictions stop a key copied out of your site from being used on someone else’s. What a browser-safe key cannot do:

• It cannot be used without an Origin header that matches its list. A non-browser caller, such as a server or a script, gets 403 with origin_denied. Use a server-side key there.
• It cannot be used from outside its IP ranges, when it has any (403 with ip_denied).
• It cannot read drafts. Draft preview for server-rendered sites is a separate permission, Allow draft preview, that only a server-side key can have.

The origin list is not authentication. The browser enforces it, and any non-browser client can send whatever Origin header it likes. To keep a non-production environment private, restrict its key to your office or VPN address range. The IP list is checked on the server.

The Delivery API accepts cross-origin requests from any origin, and it judges the actual request against the key’s allowed origins. Because of this, an origin_denied error is readable by your page rather than showing up as an opaque CORS failure.

A delivery key can also be limited to a realm, chosen when you create it. It then serves only the sites that realm and the realms below it own: GET /sites lists just those, and asking for any other site answers 403 with key_realm_mismatch. A key with no realm serves every site. The check is on the site’s owner, so one key per brand is enough to keep Brand A’s key from reading Brand B.

Management keys

A management key lets a script, a build pipeline or an AI agent create, change and publish content through the Content Management API. Two choices decide what it can do:

• Its role decides which content it may touch. The key acts exactly as that role does: the same folder permissions, the same workflow gates.
• Its scopes decide what kind of operation it may perform:

Scope	Allows
content.management.read	Reading content and planning a change without applying it
content.management.write	Applying a bundle of changes, and uploading files
content.management.publish	Publishing
content.management.authoring	Creating, editing and deleting individual items

A key with only content.management.read can report exactly what a change would do while being unable to make it, which makes it safe for a pull-request check.

A management key is bound to one authoring environment and one realm. To run a pipeline against staging and production, create two keys; to run it for two brands, create a key for each. The key reads its own realm and the realms above it, and writes only its own. whoami reports the realm, and the tools that take a realm option only check that it matches. Management keys need the Pro plan or above (a trial counts).

A management key must never reach a browser. It can be restricted to IP ranges but never to origins, and the Management API sends no CORS headers at all, so browsers cannot call it. See Content as code.

Forms SDK keys

A Forms SDK key reads your organization’s published form definitions, for rendering forms with @ebitex/forms-sdk. Only an organization Owner can create one, in Hub, and it needs the Read Forms via the SDK scope. It cannot read submissions or write anything. It is a server-side credential: fetch the form on your server and pass the result to the browser. Submitting a form needs no key at all. See Render a form.

Audience keys

Audience has two key kinds of its own, and neither is bound to an authoring or delivery environment: Audience holds one population of people per organization. A management key carries up to three scopes (audience.management.read, audience.management.write and audience.management.erase), is for your servers only, and can be limited to IP ranges. A delivery key carries the audience.delivery.read scope, which is what resolve, claim and sign-in need; with no origin or IP restriction it is a server key, and with one it is browser-safe. See Knowing your audience.

Which key to use

You are building	Use
A static site or single-page app that fetches content in the browser	A browser-safe delivery key
A server-rendered site, a static build step, or a back-end service	A server-side delivery key
A server-rendered site that shows editors their drafts in live preview	A server-side delivery key with Allow draft preview
A pipeline or agent that writes or publishes content	A management key, with the fewest scopes that work
A page that renders an ebitex form	A Forms SDK key, on the server
A server that identifies visitors or reads and writes people	An Audience management key, with the fewest scopes that work
A site that asks which audiences a visitor is in	An Audience delivery key (browser-safe if the page asks in the browser)

Errors every key shares

Response	Meaning
401 with missing_api_key	No Authorization header
401 with invalid_api_key	The key is unknown, revoked or expired. The API does not say which
403 with scope_denied	The key is valid but lacks the scope this operation needs. The response names it
403 with key_realm_mismatch	A delivery key limited to a realm asked for a site owned outside that realm
402 with payment_required	The organization’s subscription needs attention
429	A rate limit or quota was exceeded. Retry-After says how long to wait

Every response carries an X-Request-Id header. Log it with any failure and quote it to support.