Role-Based Access Control (RBAC)

Zeotap uses role-based access control to manage who can access and modify resources within a workspace. Access is granted at the group level, and nowhere else. A group lives on your organization, holds people, and is granted a role on each workspace it should reach — there is no way to add somebody to a single workspace directly.

How RBAC Works

A group holds accounts. A grant gives that group one or more roles on one workspace. Your permissions in a workspace are the union of the roles held by every group you belong to that reaches it. Permissions are checked on every API request and UI action — if you lack the required permission, the action is denied.

Core Concepts

Membership is derived

There is no workspace membership record. “A member of this workspace” means “in a group that holds a grant on it” — which is why the Members tab can tell you why somebody has access, naming the group and the role, and why removing their access is one edit in one place rather than a hunt through several.

Additive Permission Model

Zeotap uses an additive permission model — permissions are granted, never denied. Your effective permissions in a workspace are the union of the roles every group you belong to holds on it. There is no concept of “deny” rules or permission overrides.

This means:

• If a role a group of yours holds includes a permission, you can perform that action
• Belonging to two groups that reach the same workspace gives you both roles’ permissions
• There is no way to selectively deny a permission that one of those roles grants

Permission Evaluation

When you perform an action (via the UI or API), Zeotap:

1. Finds every group you belong to that holds a grant on this workspace
2. Unions the permissions of the roles those grants carry
3. Checks whether the required permission is in the union

Two things sit alongside that. A platform administrator holds the Admin role’s permissions in every workspace without a grant, plus whatever their own groups grant there — so a platform administrator who is also in a group holding Owner on a workspace can delete it. And a request made with a REST API key is first narrowed to the key’s declared scopes, so a key can never reach past what it was created for — not even through its creator’s access.

The check runs in the service layer, on every call that reads or changes something, so the UI and the API are held to the same rule.

Organization administrators reach everything

Every organization is created with two system groups, which cannot be renamed or deleted:

These are ordinary groups with one unusual grant: instead of naming a workspace, it names the whole organization. That is why a workspace created tomorrow is already reachable by your administrators with nothing to configure — and why taking somebody out of Organization admins closes every one of those doors at once.

Organization administration is membership of Organization admins. There is no separate role on the roster, and the API refuses a removal that would leave the group empty.

Built-in Roles

Zeotap provides three built-in roles that cover common organizational patterns:

See Roles for a detailed permission comparison.

In addition to these built-in roles, organization administrators can create custom roles with any subset of permissions. A custom role belongs to the organization, so one role is written once and can be granted in every workspace in it. See Roles for details.

Permission Categories

Permissions are grouped by the resource they act on. Most categories pair a read with a write; a few add a verb of their own, such as syncs.trigger or deletion_rules.execute.

Total: 120 permissions across 43 categories. One of them, demo.seed, is carried by no built-in role and reaches only demo workspaces.

See Permissions for the complete reference table.

Groups

Groups organize people into logical teams, and they are the only way access is granted. A group serves two purposes:

• Grant access — a grant gives the group one role on one workspace. The same group can be Admin in one workspace and Member in another; the role belongs to the grant, not to the group.
• Control data visibility — groups are the assignment target for access policies. When a group has access policies, its members’ queries are automatically filtered.

A group carries no permissions of its own. If you want a group to have an unusual combination of permissions, create a custom role that says so and grant that — which also means the combination has a name, and can be granted to a second group later.

See Groups and Access Policies for details.

Quick Start

1. Understand the Default Groups

Every organization starts with Organization admins and Organization viewers. Whoever created the organization is in the first one, which is what gives them Owner on every workspace in it.

2. Make a Group per Team, and Grant It What It Needs

People are invited to the organization, and the invitation names the groups they land in. Then grant each group a role per workspace.

For most teams, start with the Member role, which reads everything and changes nothing. Where a team needs to build — models, audiences, syncs — grant them a custom role carrying the write keys for their area rather than Admin.

3. Create Groups for Data Access

If different teams need to see different portions of data, create groups and assign access policies:

1. Create a group (e.g., “EMEA Team”)
2. Create an access policy (e.g., region = 'EMEA')
3. Assign the access policy to the group
4. Add members to the group

4. Set Up Destination Policies

If you need to control where data can flow, create destination policies to block, transform, or rate-limit syncs.

API Reference

Groups, roles and grants are organization-scoped — {orgId} is your organization ID. The two workspace-scoped reads stay where they are, because they answer questions about one workspace. See Base URL for your instance’s API base URL and Authentication for the required Authorization and X-Workspace-ID headers.

# Groups
GET    /api/v1/organizations/{orgId}/groups
GET    /api/v1/organizations/{orgId}/groups/{groupId}
POST   /api/v1/organizations/{orgId}/groups
PUT    /api/v1/organizations/{orgId}/groups/{groupId}
DELETE /api/v1/organizations/{orgId}/groups/{groupId}
 
# Group membership
GET    /api/v1/organizations/{orgId}/groups/{groupId}/members
POST   /api/v1/organizations/{orgId}/groups/{groupId}/members
DELETE /api/v1/organizations/{orgId}/groups/{groupId}/members/{accountId}
 
# The grant — one group, one workspace, its roles
PUT    /api/v1/organizations/{orgId}/groups/{groupId}/workspaces/{workspaceId}
DELETE /api/v1/organizations/{orgId}/groups/{groupId}/workspaces/{workspaceId}
 
# Custom roles
GET    /api/v1/organizations/{orgId}/roles
POST   /api/v1/organizations/{orgId}/roles
PUT    /api/v1/organizations/{orgId}/roles/{roleId}
DELETE /api/v1/organizations/{orgId}/roles/{roleId}
 
# Read from one workspace: who reaches it, and which groups grant that
GET    /api/v1/workspaces/{id}/members
GET    /api/v1/workspaces/{id}/groups
 
# Group access policies
GET    /api/v1/workspaces/{id}/groups/{groupId}/subsets
PUT    /api/v1/workspaces/{id}/groups/{groupId}/subsets
 
# The caller's own effective permissions, and the full catalog
GET    /api/v1/workspaces/{id}/permissions/me
GET    /api/v1/permissions

There is deliberately no POST /workspaces/{id}/members/invite, no PUT …/members/{accountId}/role and no DELETE …/members/{accountId}. Adding somebody to a workspace means putting them in a group that reaches it; changing what they can do means changing the role on a grant; removing them means taking them out of the group, or taking the grant away.

See the API Reference for full request/response schemas.

Pages in This Section

• Roles — Built-in role definitions and permission comparison
• Permissions — Complete permission reference (120 permissions, 43 categories)
• Groups — Creating and managing groups
• Managing Members — Inviting people to the organization, and granting them workspaces