# CMS

Canonical page: https://docs.ovok.com/cms

The Ovok CMS holds the content your app needs that FHIR does not model: **legal pages**, **UI translations**, **release notes** and content types you define yourself. You write it once in the Ovok Console, and your apps read the published version over a public, cacheable API.

## What you can read [#what-you-can-read]

| Collection | What it holds | Who may read it |
| --- | --- | --- |
| `legal-pages` | Terms, privacy and similar pages, with a localised title and body. | Anyone who names your tenant code. |
| `translations` | UI text, one document per group, with a localised value for each key. See [Use Ovok CMS with i18n](/cms/use-ovok-cms-with-i18n). | Anyone who names your tenant code. |
| `release-notes` | Release notes, with tags and a publish date. | A CMS API key, or a signed-in user of your project. |
| `posts` | Blog posts, with a localised title, excerpt and rich-text body, a publish date and a slug. | A CMS API key, or a signed-in user of your project. |
| Your own content types | Items you define in the Console. | A CMS API key, or a signed-in user of your project. |

Ovok decides which collections are open to anyone; an operator can change that list for a deployment.

## The routes [#the-routes]

| Route | Page |
| --- | --- |
| `GET /v1/public/cms/collections/:collection/items` | [List the items of a collection](/cms/list-collection-items) |
| `GET /v1/public/cms/collections/:collection/items/:slug` | [Get an item by slug](/cms/get-collection-item) |
| `GET /v1/public/cms/:contentTypeSlug/items` | [List the items of a content type](/cms/list-content-type-items) |
| | [Use Ovok CMS with i18n](/cms/use-ovok-cms-with-i18n) |

## Enable the CMS [#enable-the-cms]

CMS enablement is managed for the tenant in the Ovok Console. The Console records the resulting state in the [`CONTENT_ENABLED`](/settings-and-features/settings/content-enabled) project setting and manages authoring access and billing. Setting that marker through the project settings API does not enable or disable the complete CMS workflow, and the public-delivery routes do not read it.

<Recording name="ovok-console-cms-enable" alt="Checking the tenant CMS setting in Console Settings and creating the first CMS post" />

Your project's content space is created the first time the Console or an app uses the CMS. It needs your project's [tenant code](/authentication#find-your-tenant-code), and a brand-new code can be refused as unknown for up to a minute.

## Tenants [#tenants]

Content belongs to a **tenant**: your project, named by its tenant code. The sandbox and production do not share content, so write it on the API your app reads.

| You send | Where | Meaning |
| --- | --- | --- |
| `tenant` | Query, or the `x-ovok-tenant-code` header | Your tenant code. |
| `projectId` | Query | Your project's id, a UUID. Use it when you do not have the tenant code. A tenant code takes precedence if both are sent, but the project ID must still be a valid UUID. |

- **Name the tenant on every read.** A signed-in user may leave it out and reads their own project; anyone else gets `400`.
- **Headers beat query values, even empty ones.** An empty `x-ovok-tenant-code` header hides `?tenant=`.

## Who can read content [#who-can-read-content]

Three ways in, tried in this order:

| Way | How | Reads |
| --- | --- | --- |
| A **CMS API key** | `x-api-key: <key>`, `Authorization: Bearer <key>` or `?apiKey=<key>`, plus the tenant | Published content of the key's own project. |
| An **open collection** | Nothing. Only the tenant code. Applies to `legal-pages` and `translations` by default, and only on the collection routes. | Published content of the tenant you name. |
| A **signed-in session** | An Ovok access token as `Authorization: Bearer <token>` | Published content of the user's own tenant only. |

Anything else answers `401`.

- **A key reads only its own project's tenant.** A request with a key must name the tenant; a key of another project answers `401`. See [API keys](#api-keys).
- **Keep keys on your server**, not in a browser or mobile app. Use an open collection or a signed-in session there.
- **A session that names another tenant gets `403`**, not `401`, so the SDKs do not sign the user out. The exception is an open collection: a signed-in user can read another tenant's `legal-pages` or `translations` by naming it.
- **Authentication comes before everything else.** `GET .../collections/users/items` without a key answers `401`, even though no such collection is served.

## API keys [#api-keys]

Each project has its own CMS API keys. A project admin manages them in the Console on the **CMS** page, under **CMS API keys**:

<Recording name="ovok-console-cms-api-keys" alt="Creating a CMS API key in the Console and copying it when it is shown once" />

- **A new key is shown once.** Copy it then; Ovok cannot show it again.
- **Each key shows its name, a short prefix and when it was made**, never the key itself.

- **Every project starts with a **Default key**.** Revoke it once your apps use keys of their own.
- **At most 20 keys per project**, the default included. A 21st answers `409`.
- **Revoking takes effect at once**, but a response a CDN already cached is served until it expires; see [caching](#caching).
- Ovok stores only a hash of each key.

## Languages [#languages]

The CMS has every ISO 639-1 language as a bare two-letter code, 183 in all, such as `de`, `it` or `zh`. `en` is the default. Pass `locale=it`.

- **A malformed tag answers `400`:** `en_US`, `DE` and `all` are refused.
- **Use the bare codes.** A tag such as `de-DE` is accepted, but the CMS does not have it and answers in English.
- **The Ovok SDKs read four of them.** They map `de-DE` to `de` for you, but only for `de`, `en`, `fr` and `es`; any other app language is read as `en`. For another language, call the API with the bare code yourself, as in [Use Ovok CMS with i18n](/cms/use-ovok-cms-with-i18n).
- A text or textarea field with no value in the language falls back to English **field by field**.

## Published content [#published-content]

Only documents with `status` `published` are returned. A draft, and a document that does not exist, look the same: not found. There are no versions or scheduled publishing: `publishedAt` is an ordinary date and hides nothing.

Rich text is returned as the editor's JSON structure, not as HTML.

## Shared content [#shared-content]

Ovok keeps a shared tenant of its own, which contributes documents to every tenant:

- On the list routes, its published documents are **merged** with yours.
- On the get-by-slug route, it is the **fallback** when your tenant has no document with that slug.
- **Your document wins** when the slug is the same. A `translations` group of yours replaces the shared group of the same slug **whole**, so a group with one key hides the shared group's other keys.
- The merge is skipped when either side has more than 200 published documents, and your own list is returned unmerged.
- A failing shared read never breaks your read: you get your own documents.

## Caching [#caching]

| Response | `Cache-Control` |
| --- | --- |
| A tenant named by code or project id | `public, s-maxage=60, stale-while-revalidate=300` |
| A signed-in user who names no tenant | `no-store` |
| An error | None |

A tenant-named response also carries a `Vary` header on the tenant, project, API key and `Authorization` headers. Ovok caches each read for about 60 seconds, so an edit shows up within a minute, plus up to about 5 minutes more behind a CDN. Nothing purges the cache when you publish.

## Browsers and CORS [#browsers-and-cors]

For an allowed origin, Ovok's CORS policy accepts `Content-Type`, `Authorization`, `Accept-Language`, `If-Match`, `X-Ovok`, `X-Tenant-Code` and the tracing headers. **`x-api-key` and `x-ovok-tenant-code` are not allowed**, so a browser must send:

- the key as `Authorization: Bearer <key>` or `?apiKey=`;
- the tenant as `?tenant=`.

A key in the URL can end up in logs. Prefer the header from a server.

## Limits [#limits]

| What | Value |
| --- | --- |
| `page` | 1 to 100. A non-number falls back to 1. |
| `limit` | 1 to 50. Default 20. |
| Documents readable per list | 5,000 (50 per page, 100 pages) |
| Content type route | At most 100 items, no paging, no `sort`, no `locale` |
| Slug | Lower-case letters, digits, `-`, `_` and `.`; starts with a letter or digit; up to 128 characters |
| Usage | Public CMS reads do not count towards your project's API usage statistics or your plan's request cap. |
| Rate limit | Key-only and unauthenticated calls use the unknown-caller limit: 1,000 per minute per route and IP address. Signed-in calls use the caller's role limit per route: patients and related people 100 per 30 seconds; practitioners 200 per 30 seconds; admins and client applications 1,000 per 30 seconds. Over a limit returns `429`. |

## Errors [#errors]

| Status | `message` | Cause |
| --- | --- | --- |
| [`400`](/errors/malformed-request) | `Public CMS delivery requires` a tenant code, a project id, or a signed-in session | No tenant is named and the caller is not signed in. |
| [`400`](/errors/malformed-request) | `Unknown tenant code: <code>` | The tenant code does not exist. |
| [`400`](/errors/malformed-request) | `Invalid project id.` followed by what was expected | `projectId` is not a UUID. |
| [`400`](/errors/malformed-request) | `Invalid locale "<value>". Expected a language tag like "de" or "en-US".` | The language tag is malformed, or is `all`. |
| [`400`](/errors/malformed-request) | `Invalid sort "<value>". Expected a field name, optionally prefixed with "-".` | `sort` is not a top-level field name. |
| [`400`](/errors/malformed-request) | `Public CMS delivery with an API key requires` a tenant | A request with a key named no tenant. |
| [`401`](/errors/unauthenticated) | `Invalid or missing CMS public API key` | The collection is not open and there is no valid key or session, or the key belongs to another project or was revoked. |
| [`403`](/errors/forbidden) | `A signed-in session reads its own tenant's content` | A signed-in user named another tenant. |
| [`404`](/errors/not-found) | `Not found` | A missing, unpublished or malformed slug, or a collection that is not served. |
| [`429`](/errors/too-many-requests) | `Too Many Requests` | Over the rate limit. Wait `retryAfterSec` seconds (the `Retry-After` header). |
| [`502`](/errors/upstream-error) | `Unable to resolve` the CMS tenant | The CMS is unreachable. Retry. |

Errors share the format in [errors and troubleshooting](/authentication/troubleshooting); a [`429`](/errors/too-many-requests) body also has `retryAfterSec`. See [the rate-limit headers](/slim-apis#errors-on-every-route). A CMS failure is never answered with an empty `200`.

## Related [#related]

- [`CONTENT_ENABLED`](/settings-and-features/settings/content-enabled)
- [Authentication](/authentication)
- [Use Ovok CMS with i18n](/cms/use-ovok-cms-with-i18n)
