/ Search

Search Epistola

Find documentation, integration guides, tour steps, blog posts and pages.

DocsIntegrationsTourBlogPage
↑↓↵esc

Work in progress — The Learn section is being expanded; alpha, beta, and preview capabilities are labelled where relevant.

Access & Permissions

Give users and integrations only the access they need.

Access and permissions

Epistola separates access by tenant. Roles grant permissions for viewing and editing content, publishing versions, generating documents, or administering the tenant. A person’s effective access is the combination of all roles assigned to them.

Choose a role for a user

Use the smallest role set that supports the person’s work:

  • Content Viewer — Inspect templates, reference data, and generated documents.
  • Content Author — Create and edit templates, themes, stencils, and reference data.
  • Document Generator — Generate documents.
  • Content Publisher — Publish and archive template and stencil versions. Publishing is separate from tenant administration.
  • Tenant Administrator — Manage tenant settings, users, API keys, catalogs, diagnostics, backups, and restore operations.

Roles are composable and do not implicitly include one another. For example, a user who needs to edit and publish content needs both author and publisher access.

Create an API key

API keys authenticate external systems calling the REST API. Create one from the tenant’s API Keys page:

  1. Choose New API key and give the key a recognizable name, such as Valtimo test or Production generation.
  2. Select the exact tenant roles the integration needs. A generation-only integration normally needs Document Generator, not authoring or administration.
  3. Set an expiry date when the key should be temporary or rotated regularly.
  4. Create the key and copy the secret immediately.

The secret is shown only once and cannot be recovered or edited after creation. Store it in the connected system’s secret manager, never in source control or client-side code. API keys are tenant-scoped and cannot be used to access another tenant.

Operate and rotate keys

The API key list shows its name, visible prefix, assigned scope, creator, creation time, last use, and expiry. Keys cannot be modified after creation: create a replacement with the desired scope, update the integration, verify it, and then delete the old key. Deleting a key takes effect immediately and stops any system using it from authenticating.

For Valtimo or another connected system, configure the key together with the Epistola base URL, tenant, environment, and template mapping described in Connected Systems.

Review access regularly

Review user roles and API keys when teams change, a project goes live, or an integration is retired. Prefer separate keys for separate environments and integrations, give each key the least privilege possible, set expiries where practical, and remove unused credentials promptly.