All three share the same three levels —
viewer, editor, manager — and the same assignments payload. What a level means differs per resource: see Permissions for the Catalog axis and Assign Object Permissions for secrets and live connections.
Data-level permissions apply on Growth and Custom plans, and the plan gate is not symmetric across the axes. The Catalog endpoints return
403 outright below Growth. On the other two, grants can be written but do not restrict anything — every member still sees everything until the plan enforces.Before you start
Permissions are granted to Members. Owners and Admins bypass data-level access entirely, so there is nothing to grant them — which is why they never appear in the recipients endpoints. You will need an API key, and it matters who created it. Read the ceiling rule below before you build anything.The ceiling rule
An API key is not an all-powerful credential. It acts as the person who created it, carrying their id and their role. This is the same rule the app applies to that person, with no separate concept for machines — so the fastest way to reason about what your key can do is to ask what its creator can do in the UI. It also means a key does not outlive its creator’s authority: demote the person and the key narrows with them. If you are automating workspace-wide provisioning, create the key as an Owner or Admin. If you are letting a team self-serve within their own domain, a Member’s key is the right ceiling.The flow
1
Find the recipient
Grants target a user or a permission group by UUID, and the recipients endpoint is the only public source of those ids — there is no separate user or group listing.An empty
users list usually means the person is an Owner or Admin, or is not an active member — not that the search failed.2
Find the resource
Catalog resources come from List Layers and the folders, tables, and volumes endpoints. Granting on a layer covers everything inside it, so prefer the coarsest resource that expresses your intent.
3
Assign
One call can create, change, and revoke at once. Each assignment block pairs every recipient with every resource and applies one level.The response tells you exactly what changed:
4
Verify
List the grants back, filtered by recipient.
indirect_user includes grants the person receives through a group, which is what you usually want when auditing what someone can actually reach.5
Revoke
Two ways, and they differ in what you need to know beforehand. Send Revoking is a soft delete: the grant stops applying immediately and leaves the listing, and the row is retained with the actor and timestamp for the audit trail.
permission_level: null through the assign endpoint to revoke by recipient and resource, or DELETE the grant if you already hold its id.How an assignment resolves
Three behaviors surprise people, and all three are deliberate. It is an upsert, not a create. You describe the access you want; Nekt computes the difference against what exists. Sending the same request twice is safe — the second call reports nothing created, updated, or revoked. Each block is a cross product. Two users and three tables in one assignment produce six grants. To apply different levels, use separate blocks.null is a verb. permission_level: null revokes the pair rather than being a no-op or an error.
One more asymmetry worth knowing before you automate:
notify_members sends email on the Semantic Layer axis and is silently ignored on the Catalog axis. If you are provisioning in bulk, leave it false.Group grants versus direct grants
A recipient can be a user or a permission group, and a person’s effective access is the union of every grant that reaches them. A group grant is not a snapshot: adding someone to the group later gives them that access, and removing them takes it away, with no permission call at all. Managing a stable team through a group and reserving direct grants for exceptions keeps the number of API calls proportional to the number of teams rather than the number of people.Errors
The
403 messages name the rule that refused, for example Member users cannot assign manager permissions. Read the body before assuming the key is broken.
Reference
Assign Permissions
Grant, change, and revoke Catalog access in bulk.
List Recipients
The users and groups that can receive a grant.
Assign Object Permissions
The same flow for secrets and live connections.
Assign Semantic Layer Permissions
The same flow for catalogs, folders, and documents.
Permissions in the app
What each level allows, module by module.