Preview vs. Live documentation for the dotCMS Content Management System

Live Content vs. Previewing Content

dotCMS requires an API key to access content and pages stored in dotCMS. These dotCMS API keys can be generated from the command line or from the backend of dotCMS from the User Manager screen. In dotCMS, an API key grants the permissions of the user to which they are issued, including permissions tied to any roles that the user might have. All content and API calls are permission-based and will return differently based on the key's user permissions.

dotCMS has the concept of Front End users and Back End users. Front End users can only see live/published content. Back end users can preview drafted/unpublished content. This means that if an API key is generated for a “Front End” user (a checkbox in the User's Account) then that key will only be able to view and access published/live front-end content (this includes content that has CMS Anonymous access set to READ). If an API key is generated for a “Back End” user (again, a checkbox in the User's Account), then that key will enable preview access to unpublished/working content based on the “Back End” user's permissions.

API KeyAccess
Front End User API KeyCan only see live/published content
Back End User API KeyCan see unpublished/staged and live/published content

Strategies for Authentication

When using the dotCMS APIs, there are a number of strategies you can use to set up preview environments, where unpublished content can be viewed and previewed vs. live environments, where only published content can be accessed.

Live/Published Content : Client Side Key

For publically accessable and read only sites, an API key can be generated for a “Front-End” user and embedded in an app or SPA that is used to make the API requests. While the embedded API key would be discoverable by a snooping web developer, it only grants read access to public content and is not unlike anonymous read access on any web property.

Previewing Content : Client Side Key

If your content is not sensitive and your preview environment is only accessable by trusted users, the same strategy can be used to create a “Preview” user key in dotCMS. To do this, you create a limited “Back-End” user in dotCMS and with them generate an api key or .env file for your preview environment. While this back-end api key is easy to use, it has the significant downside that it will also be discoverable by anyone who can access your preview environment. That said, the risks of this approach might be acceptable if simplicity is important, the content is not overly sensitive and the keys' permissions are limited only to reads and/or specific pages or content types.

Previewing Content : an API Key Facade

It is possible to use your ingress/proxy layer and append an api key as a header to incoming requests. This approach effectivly hides the API key from users and avoids having to embed the API key in an SPA or client side code. dotCMS has a demonstration OSGi plugin that can be used for this purpose to transparently append an API key to incoming requests, allowing for selective access to specific apis without exposing the api key publicly. It can be configured to grant access to only a subset of API endpoints.

Previewing Content : dotCMS Auth before

A more involved strategy requires users to authenticate against dotCMS or another 3rd party authentication system before they access the preview url. Out of the box, dotCMS provides an authentication api that could be used to authenticate users before they can view any content. The api call below authenticates user and sets a cookie on the user's browser which is then used to authenticate further dotCMS API calls. The authenticated user's browser passes this cookie with each API request and is granted the permissions based on their dotCMS permissions.

curl '' -v \
-H 'Content-Type: application/json' \
--data-binary ' 

Previewing Content : 3rd Party Auth before

dotCMS can also integrate with 3rd party authentication mechanisms such as OAUTH, SAML or AD. When an unauthenticaed user accesses the preview site, they are redirected to the 3rd party authentication mechinism. Once authenticated there, they are returned to your app with a token or a cookie they can pass to dotCMS, which will validate the token against the 3rd party and map the newly authenticated user to a user in dotCMS. dotCMS provides both an OAuth and SAML plugins to do just this.