API keys & content export

Create a credential for a specific integration

API keys let trusted software use the authenticated CMS API without an interactive browser session. Creating and revoking keys is an administrator function. A key is associated with its owner and a set of action scopes. Requests must satisfy both the current owner’s permission rules and the key’s scopes; a scope is not an independent grant of administrator authority.

1. Open API keys from Settings. Choose the creation action and enter a recognizable name such as Internal content importer.
2. Select only the required actions: read, create, edit, publish, unpublish, preview or media. Read is selected initially. Write integrations generally also need read because returned resource views are permission-checked.
3. Choose an expiry. The interface offers 7, 30, 90, 180 or 365 days and initially selects 90 days.
4. Create the key and copy the complete token immediately into the integration’s secret storage. The token is shown once; the server stores a hash and identifying prefix, not a recoverable plaintext copy.
5. Use Revoke when the integration is retired or a token may be exposed. If the original token is lost, create a replacement and revoke the old one.

Sources: API key controls and export link; CMS API routes and export implementation; Bearer credential resolution and API request authentication; Permission and scope intersection.

Use the API deliberately

The CMS REST interface is under /api/cms. Integrations authenticate with an Authorization header containing Bearer followed by the token. Keep the token in a server-side environment variable or secret store, never in public browser JavaScript, a URL query string or a source-code commit. The example below describes the request shape and uses a placeholder.

GET /api/cms/resources?kind=content&type=post&page=1&pageSize=20 HTTP/1.1
Host: your-cms.example
Authorization: Bearer <your-private-api-token>

Read the API contract before writing content. Saves include the expected working revision to detect conflicting edits. Publication actions name the exact target revision and expected publication version, with an idempotency key for safe retries. A conflict response calls for reloading current state and resolving the difference rather than blindly replaying an outdated body.

The server returns structured errors for invalid input, forbidden actions and conflicts. Use the returned error and the contract to decide whether to correct the payload, request additional authority or reload the record. The administrative API is not an anonymous public content feed. Revoked or expired credentials, a disabled owner or changed owner permissions can stop previously working requests.

Sources: REST API contract; CMS API routes and export implementation; Bearer credential resolution and API request authentication; Permission and scope intersection.

Download the workspace content package

1. As an administrator, open Settings and select Download export under Export workspace.
2. Save the JSON file in a location appropriate for unpublished and private content. The package is a workspace content snapshot, not only a copy of the visible website.
3. Check the format and version before processing it. The native format is gcms-native, version 3, including language configuration, translation identities, revision locales, type definitions and exact version pins, component release/publication evidence, instance pins and catalogue state. Use the included IDs and manifests to preserve references when building migration tooling. This is separate from the default-language-only grocms-site-v1 installation manifest.

The export includes site resources, retained revisions, route records, content-type and taxonomy definitions, revision-to-term relationships, resource and media reference manifests, and media metadata such as filenames, alternative text, hashes, dimensions and storage keys. Private and trashed resources may be included. A repeatable-read database transaction keeps the exported tables consistent with one snapshot.

The package excludes login accounts, passwords, sessions, API secrets, invitations, preview tokens, review and schedule records, audit events, background jobs, and actual media file bytes. It is therefore not a complete disaster-recovery backup. These omissions also mean it cannot reproduce the full operational history of the workspace.

Export selected in a content list downloads selected-content.json with format gcms-selected-snapshots, version 1. It includes the selected entries on the current list page and their loaded working revisions, not all retained revisions or a full workspace package. This download is available for entries the account can read. The separate Export button and Settings → Download export request the administrator-only full content package.

Sources: CMS API routes and export implementation; REST API contract; Selected-content export format and scope; Content list selection and full-export permission.

Know the import and backup boundaries

There is no general Upload workspace JSON restoration screen in the current CMS. The export supports inspection, portability and developer-led migration; it does not imply an implemented one-click importer. Brand token import is a different, limited operation for theme values. For a full restore, use the documented PostgreSQL and media-volume backup procedure.

Before writing an integration that changes many records, test on a separate installation with a backup and realistic references. Publishing may reject missing dependencies, occupied routes or stale revisions even if a draft save succeeded. Keep import credentials separate from routine reading credentials so a reader does not accidentally acquire publication rights.

Sources: REST API contract; CMS API routes and export implementation; Backup operations.