Permissions
How Celiq enforces access — role-based middleware gates layered with row-level Data Keys and column-level Data Gates.
When to use it — When you need to understand why an action is blocked, or when you are planning who should hold which role before inviting people.
Where to find it — There is no separate "Permissions" editor. You set the role per person in Lumen → Users, and you define row/column rules in Lumen → Security (and in CML).
Who can use it — Luminary assigns roles and mints workspace credentials; Weaver can manage teams and build the semantic model. Tracer and Lens are subject to permissions but cannot change them.
Permissions in Celiq are not edited one checkbox at a time. Instead, each person holds exactly one role, and that role determines the actions they can take and the pages they can open. Layered on top, Data Keys and Data Gates narrow what data a person sees inside the screens they are allowed to reach.
This page is the conceptual bridge between Roles and the two security pages. Read it first if you are deciding how to lock down a workspace, then move on to Data Keys and Data Gates for the row- and column-level rules.
Overview
Celiq enforces permissions in two layers that always apply together:
- Role gates — Every backend route and every protected page checks your role before it runs. The four roles form a strict hierarchy: Luminary > Weaver > Tracer > Lens. A guard names the minimum role, and anyone at or above that level passes.
- Data-level security — Once a role check passes, your query is still rewritten before it touches the warehouse. Data Keys add row filters; Data Gates strip columns. Luminary bypasses both; Weaver bypasses column gates but is still subject to row keys.
There is intentionally no granular per-permission editor UI — you cannot, for example, grant one Tracer the ability to mint API keys without making them a Luminary. Permissions are determined entirely by the assigned role plus the CML-defined (or UI-defined) data keys and gates.
When to use it
- You are setting up a new workspace and want to map people to the right role before sending invites.
- A teammate reports "this action requires luminary role or higher" or a page redirects them home, and you need to know which role unlocks it.
- You want regional or team-scoped data restrictions and need to decide between a Data Key (rows) and a Data Gate (columns).
- You are auditing who can provision credentials (API keys), manage connections, or see billing.
Concepts
| Term | What it means |
|---|---|
| Role | One of Luminary, Weaver, Tracer, Lens. Assigned per person; the single biggest determinant of what you can do. |
| Role hierarchy | luminary (4) > weaver (3) > tracer (2) > lens (1). Guards check that your level is at or above the required level. |
| Role gate | A middleware check on a backend route — anyAuth, tracerAndAbove, weaverAndAbove, or luminaryOnly — plus the equivalent route guards in the app shell. |
| Permission flag | A named capability (e.g. create_nodes, manage_users, view_billing) that a role carries. The frontend uses these to show or hide pages; you do not edit them directly. |
| Data Key | Row-level security (RLS). Restricts which rows of a node a non-Luminary user can see. |
| Data Gate | Column-level security (CLS). Hides specific fields from users below Weaver. |
Getting started
You do not "open Permissions" — there is no such screen. Instead you work with the two inputs that produce permissions:
- Roles are assigned in Lumen → Users. Changing a person's role is how you change what they can do.
- Data Keys and Data Gates are defined in Lumen → Security, or declared in CML alongside your nodes.
Prerequisites:
- You must be a Luminary to change roles, mint or revoke workspace API keys, manage connections, or view the audit log and billing.
- You must be a Weaver or above to create teams or build the semantic model (nodes, domains).
Step-by-step
Decide the role, not the permission
Open Lumen → Users and pick the role that matches what the person needs to do. Because there is no per-permission editor, the role is your only lever — choose the smallest role that covers their work (see the action map below).
Confirm the action they need maps to that role
Use the table in Examples to confirm. For instance, if they need to import or create nodes, they need at least Weaver (which carries create_nodes); a Tracer cannot reach the Import or Forge pages.
Layer on row restrictions with Data Keys
If the person should only see certain rows (e.g. one region), go to Lumen → Security and assign a Data Key on the relevant node. Without an assignment, a keyed node returns no rows for non-Luminary users — this is the safe default, not an error.
Layer on column restrictions with Data Gates
If specific columns must be hidden (e.g. cost, margin, PII), define a Data Gate on those fields. Gates hide columns from everyone below Weaver; Luminary and Weaver still see them.
Verify by viewing as that person
Use the View as option (see Sudo) to confirm the combined effect of role plus keys and gates before you tell the person they are set up.
Examples
The table below maps common actions to the real guard that protects them. "Minimum role" is the lowest role that passes the gate.
| Action | Guard in code | Minimum role |
|---|---|---|
| Read charts, dashboards, signals | anyAuth | Lens |
| Run Discover, use Orion, pin to a Mosaic | role permission (run_discover, use_orion) | Tracer |
| View teams and members | tracerAndAbove | Tracer |
| Create, rename, or delete a team; assign members to a team | weaverAndAbove | Weaver |
| Import data or open Forge (build the semantic model) | create_nodes permission | Weaver |
| Mint a workspace API key | luminaryOnly | Luminary |
| Revoke a workspace API key | luminaryOnly | Luminary |
| Manage connections, manage users, view audit log, view billing | role permissions (manage_connections, manage_users, view_audit, view_billing) | Luminary |
A role gate is just middleware naming the minimum role. For example, the workspace-teams routes apply two different gates so that anyone can see teams but only builders can change them:
GET /api/workspace-teams tracerAndAbove // Tracer, Weaver, Luminary can list
GET /api/workspace-teams/members tracerAndAbove // viewing members is read-only
POST /api/workspace-teams weaverAndAbove // creating a team needs Weaver+
PUT /api/workspace-teams/:id weaverAndAbove // editing a team needs Weaver+
Provisioning credentials is the strictest gate. Minting and revoking workspace API keys is luminaryOnly — a Lens or Tracer who calls it receives a 403:
{
"error": "Requires role: luminary"
}Data Keys and Data Gates apply after the role check, at query time. A Data Key on a region column produces a row filter, while a Data Gate hides a column entirely:
node: orders
data_keys:
- column: region # row-level: each user only sees their assigned regions
wildcard: "" # an assignment of [""] grants all rows
data_gates:
- fields: [cost, margin] # column-level: hidden from users below Weaver
With the key above, a Tracer assigned ["US", "CA"] runs a query that is silently rewritten to add orders.region IN ('US', 'CA'). A Tracer with no assignment on a keyed node sees zero rows — the deny-by-default behaviour.
Best practices
- Assign the smallest role that works. Because permissions follow the role, over-granting a role over-grants everything it carries (including credential minting for Luminary).
- Reserve Luminary for true admins. Only Luminary can mint or revoke API keys, manage users and connections, and see billing and the audit log.
- Use Data Keys for "who sees which rows" and Data Gates for "who sees which columns." Do not try to model row restrictions with roles.
- Declare data security in CML where you can so it lives with the node definition and is reviewed alongside model changes.
- Verify with View as. The only reliable way to confirm a person's effective access is to view the app as them.
Tips
The role hierarchy means you rarely need to think in terms of individual permissions. If you can answer "what is the lowest role that should be able to do this?", you have your answer. The four levels are Lens (read-only) → Tracer (analyst) → Weaver (builder) → Luminary (admin).
Common mistakes
Forgetting that a keyed node denies by default. If a non-Luminary user reports empty results on a node that has a Data Key, the cause is usually a missing key assignment, not a bug. Assign the key (or
["*"] for full access) in Lumen → Security.Expecting Weaver to be blocked by column gates. Data Gates only hide columns from users below Weaver. Weaver and Luminary always see gated columns.
Trying to give one Tracer admin-only powers. Minting API keys, managing users, and viewing billing are tied to Luminary. The only way to grant them is to make the person a Luminary.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Requires role: luminary (403) | Action is luminaryOnly (e.g. minting/revoking an API key) and you are not a Luminary | Have a Luminary perform it, or have your role raised in Lumen → Users |
This action requires weaver role or higher (403) | A weaverAndAbove guard (e.g. creating a team) and your role is Tracer or Lens | Raise the role to Weaver or above |
| Import or Forge page redirects you home | The page requires the create_nodes permission, which only Weaver and Luminary carry | Use a Weaver/Luminary account to build the model |
Account disabled (401) | The account was disabled; the role check re-verifies active status on each request | Re-enable the user in Lumen → Users |
No token provided / Invalid or expired token (401) | Missing or expired session, checked before any role gate | Sign in again |
| A non-Luminary sees zero rows on one node | A Data Key exists on that node but the user has no assignment (deny-by-default) | Assign the Data Key (or ["*"]) in Lumen → Security — see Data Keys |
| A user below Weaver cannot see a column that exists in the model | A Data Gate is hiding that field at query time | Confirm intended; if they should see it, adjust the gate — see Data Gates |
Related pages
- Roles — the four roles and the full hierarchy that drives every gate
- Data Keys — row-level security and how key assignments work
- Data Gates — column-level security and which roles bypass it
- Users — where you assign and change a person's role
- API keys — the Luminary-only workspace credential flow
- Sudo — "View as" to verify a person's effective access