CALM Hub Entitlements
CALM Hub uses a hierarchical permission model to control who can read, write, and administer namespaces, and a flat permission model for control domains. This page explains how both models work and how to configure access.
Permission Levels
Every access grant specifies one of three permission levels:
| Permission | What it allows |
|---|---|
read | Read any document in the namespace or domain |
write | Create documents (implies read) |
admin | Full control: read, write, and manage entitlements for other users (implies read and write) |
Namespace Permissions
Hierarchy
Namespaces in CALM Hub use . as a separator to express parent/child relationships:
org
org.ecosystem
org.ecosystem.system
Access grants are evaluated across the full ancestor chain, not just the directly-targeted namespace.
Reading: AND across the ancestor chain
To read a namespace, a user must have a sufficient grant at the requested namespace and every ancestor namespace.
If any level in the chain is missing a grant for the user, access is denied — even if the target namespace itself has a grant.
Example
| Namespace | * (public) grant | bob grant |
|---|---|---|
org | read | — |
org.ab | read | — |
org.ab.cd | — | read |
org.ab.cd.de | read | — |
- Anyone can read
organdorg.ab(public grant at both levels). - Only
bobcan readorg.ab.cd(no public grant at that level;bobhas an explicit grant). - Only
bobcan readorg.ab.cd.de— even though it has a public grant, the AND check fails atorg.ab.cdfor everyone else.
This rule makes it possible to have a publicly visible parent namespace with restricted child namespaces. Removing a public grant from a namespace automatically restricts access to all its descendants, without needing to change those descendants.
Writing and Administering: OR across the ancestor chain
To write or admin a namespace, a user must have a sufficient grant at the requested namespace or any ancestor namespace.
A grant at org is sufficient to write anything under org.ecosystem, org.ecosystem.system, and so on. This lets you delegate broad access with a single grant rather than one per sub-namespace.
Creating Namespaces
To create a top-level namespace (e.g. org), a user must be a global admin.
To create a child namespace (e.g. org.ecosystem), a user must be a global admin or have admin on the direct parent namespace (org in this example).
Domain Permissions
Control domains use a flat permission model — there is no ancestor chain. A grant on domain payments applies only to payments; it does not cascade to any other domain.
| Permission | What it allows |
|---|---|
read | Read content in the domain |
write | Read and write content in the domain |
admin | Read, write, and manage entitlements for the domain |
Only global admins can create and delete domains. Domain admin grants are managed through the admin UI or the /api/calm/domains/{domain}/user-access endpoints.
Public Access: the * Username
The reserved username * represents anyone — including unauthenticated users if your deployment allows it. A * grant at a namespace or domain means it is open to all users at that permission level.
username: *
permission: read
namespace: org.ab
* grants are evaluated by the same AND/OR rules as named user grants. You manage them through the same API or admin UI — * is just a username value that matches everyone.
When a namespace is created, CALM Hub automatically inserts a * read grant so the namespace is publicly readable by default. To restrict a namespace, delete that * read grant. The same applies to domains.
* can be granted write, but not admin — attempts to create a wildcard admin grant on any namespace or domain are rejected with 400 Bad Request. This prevents accidental elevation of all users to administrators.
Global Access Modes
allow-public-read flag
Setting calm.auth.allow-public-read=true makes every namespace readable by everyone, bypassing all per-namespace checks. This is the simplest option for fully open deployments. The default is false.
Global admin
A user with admin on the special GLOBAL namespace bypasses all namespace-level and domain-level permission checks. Use this for super-administrators who need unrestricted access. Global admins can:
- Read and write all namespaces and domains
- Create and delete namespaces and domains
- Manage entitlements for any namespace or domain, including granting further GLOBAL admin access
To bootstrap a new deployment, create the first GLOBAL admin grant via the admin UI in no-auth mode (or via the Swagger UI at /q/swagger-ui), then switch to a secured auth profile.
The GLOBAL namespace is a sentinel value — it is not a real namespace in the store and cannot be used to store documents.
Worked Example
Consider three users on a hub with the following grants:
| Username | Permission | Namespace |
|---|---|---|
* | read | org |
* | read | org.ab |
mark | write | org.ab |
carol | admin | org.ab.cd |
bob | read | org.ab.cd |
What can each user do with org.ab.cd?
| User | Can read? | Can write? | Can admin? |
|---|---|---|---|
| Anyone (unauthenticated) | No (org.ab.cd has no * read grant) | No | No |
mark | No (no grant at org.ab.cd for mark or * — AND fails at that level) | Yes (write grant at org.ab is an ancestor — OR passes) | No |
carol | Yes (admin at org.ab.cd implies read; * read at ancestors passes the AND check) | Yes | Yes |
bob | Yes (* at ancestors + own read at org.ab.cd) | No | No |
Managing Entitlements
Admin UI
The easiest way to manage entitlements is the built-in admin UI, available at /admin in your CALM Hub instance. Users with any admin entitlement can access it; the sections visible depend on your permission level:
- Namespace Access — available to any namespace admin; manage grants for namespaces you administer
- Domain Access — available to global admins only; manage grants for any domain
- Global Admin Access — available to global admins only; grant or revoke GLOBAL admin access for other users
REST API
Entitlements can also be managed directly through the REST API. Use the Swagger UI to explore available operations.
Grant bob read access to org.ab.cd:
POST /api/calm/namespaces/org.ab.cd/user-access
Content-Type: application/json
{
"username": "bob",
"permission": "read"
}
Make org.ab publicly readable:
POST /api/calm/namespaces/org.ab/user-access
Content-Type: application/json
{
"username": "*",
"permission": "read"
}
Remove public access from org.ab:
DELETE /api/calm/namespaces/org.ab/user-access/{id}
Grant carol admin access to the payments domain:
POST /api/calm/domains/payments/user-access
Content-Type: application/json
{
"username": "carol",
"permission": "admin"
}
Restricting a Namespace
To make a namespace private:
- Find the
* readgrant for the namespace usingGET /api/calm/namespaces/org.ab/user-access. - Delete it with
DELETE /api/calm/namespaces/org.ab/user-access/{id}.
Once removed, only users with explicit grants — or a write/admin grant on an ancestor — can access that namespace.
Removing the * grant at a parent namespace cascades access restriction down the tree automatically, because child namespaces still require the AND check to pass at every ancestor.