CMS

Store legal pages, UI translations, release notes and your own content in the Ovok CMS, and read it from your apps with the public delivery API.

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

CollectionWhat it holdsWho may read it
legal-pagesTerms, privacy and similar pages, with a localised title and body.Anyone who names your tenant code.
translationsUI text, one document per group, with a localised value for each key. See Use Ovok CMS with i18n.Anyone who names your tenant code.
release-notesRelease notes, with tags and a publish date.A CMS API key, or a signed-in user of your project.
postsBlog 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 typesItems 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

RoutePage
GET /v1/public/cms/collections/:collection/itemsList the items of a collection
GET /v1/public/cms/collections/:collection/items/:slugGet an item by slug
GET /v1/public/cms/:contentTypeSlug/itemsList the items of a content type
Use Ovok CMS with i18n

Enable the CMS

CMS enablement is managed for the tenant in the Ovok Console. The Console records the resulting state in the 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.

  1. 1CONTENT_ENABLED shows whether CMS is enabled for this tenant.
  2. 2Open CMS and choose a collection after it is enabled.
  3. 3Create the first post with a title and a unique slug.

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, and a brand-new code can be refused as unknown for up to a minute.

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 sendWhereMeaning
tenantQuery, or the x-ovok-tenant-code headerYour tenant code.
projectIdQueryYour 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

Three ways in, tried in this order:

WayHowReads
A CMS API keyx-api-key: <key>, Authorization: Bearer <key> or ?apiKey=<key>, plus the tenantPublished content of the key's own project.
An open collectionNothing. 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 sessionAn 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.
  • 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

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

  1. 1Create a CMS API key for the website.
  2. 2Copy the one-time key, then revoke it when access is no longer needed.
  • 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.

  • Ovok stores only a hash of each key.

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.
  • A text or textarea field with no value in the language falls back to English field by field.

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

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

ResponseCache-Control
A tenant named by code or project idpublic, s-maxage=60, stale-while-revalidate=300
A signed-in user who names no tenantno-store
An errorNone

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

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

WhatValue
page1 to 100. A non-number falls back to 1.
limit1 to 50. Default 20.
Documents readable per list5,000 (50 per page, 100 pages)
Content type routeAt most 100 items, no paging, no sort, no locale
SlugLower-case letters, digits, -, _ and .; starts with a letter or digit; up to 128 characters
UsagePublic CMS reads do not count towards your project's API usage statistics or your plan's request cap.
Rate limitKey-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

StatusmessageCause
400Public CMS delivery requires a tenant code, a project id, or a signed-in sessionNo tenant is named and the caller is not signed in.
400Unknown tenant code: <code>The tenant code does not exist.
400Invalid project id. followed by what was expectedprojectId is not a UUID.
400Invalid locale "<value>". Expected a language tag like "de" or "en-US".The language tag is malformed, or is all.
400Invalid sort "<value>". Expected a field name, optionally prefixed with "-".sort is not a top-level field name.
400Public CMS delivery with an API key requires a tenantA request with a key named no tenant.
401Invalid or missing CMS public API keyThe collection is not open and there is no valid key or session, or the key belongs to another project or was revoked.
403A signed-in session reads its own tenant's contentA signed-in user named another tenant.
404Not foundA missing, unpublished or malformed slug, or a collection that is not served.
429Too Many RequestsOver the rate limit. Wait retryAfterSec seconds (the Retry-After header).
502Unable to resolve the CMS tenantThe CMS is unreachable. Retry.

Errors share the format in errors and troubleshooting; a 429 body also has retryAfterSec. See the rate-limit headers. A CMS failure is never answered with an empty 200.

Last updated on

On this page