Roles
A role is a named set of permissions. Zeotap ships three built-in roles and lets you create custom ones with any combination of permissions.
A role is not held by a person — it is held by a grant, which gives one group one role on one workspace. Your permissions in a workspace are the union of the roles every group you belong to holds there. Custom roles belong to the organization, so a role is written once and can be granted in every workspace in it.
The Built-in Roles
| Role | Permissions | Who it is for |
|---|---|---|
| Owner | 206 of 207 | The person responsible for the workspace itself. The only role that can delete it. |
| Admin | 205 of 207 — everything but workspace.delete | Team leads, data engineers, platform administrators. |
| Member | 72 of 207 — read across the platform | Analysts and marketers who work in the platform without configuring it. |
Owner
Owner carries every permission but demo.seed, which no built-in role holds. workspace.delete is what separates Owner from Admin; in day-to-day work the two roles are identical.
Admin
Admin runs the platform: warehouses and destinations, models and audiences, events, journeys, identity graphs, loaders, governance policies, members, groups and custom roles. An Admin cannot delete the workspace.
Member
Member is a read role. A Member can open every part of the platform and see what is configured, what ran and what it produced, but the actions that create, change, delete or trigger something belong to Owner and Admin.
Beyond reading, a Member can converse with the AI agent (agent.write) and let it use the workspace’s connected connectors (agent_connectors.use), open the live event debugger (events.debug), manage tags (tags.write), and edit the feature library (features.write).
Five reads belong to Owner and Admin: the workspace audit log (workspace_audit.read), workspace-wide agent token spend (agent.usage.read), and the three warehouse-infrastructure reads — warehouse_users.read, execution_environments.read and cdp_working_datasets.read, which are a platform or security owner’s concern. Grant any of them to a custom role where a workspace wants a Member to see them.
If your analysts need to build models or audiences themselves, that is a custom role — not a change to Member.
Custom Roles
A custom role is a name, a description and a list of permission keys. Nothing is implied or inherited: the role allows exactly the keys you list.
Creating a Custom Role
Via the UI
- Go to Organization settings → Roles and click New role. To start from an existing role, select it and click Duplicate instead; built-in roles can be duplicated too.
- Give the role a name and a description, and choose a role to start from or No permissions.
- The new role opens on the right. Its permissions are grouped by area, with one row per resource and its actions (View, Create, Edit, Delete, and any others such as Trigger). Tick the actions the role should carry, or use Grant all for a whole area. Each change is saved as you make it.
Use Compare with to check a role against another, and Differences only to see just the permissions where the two differ.
Via the API
curl -X POST "$API_BASE_URL/api/v1/organizations/$ORG_ID/roles" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Marketing Analyst",
"description": "Builds audiences over existing models",
"permissions": [
"models.read",
"audiences.read", "audiences.write",
"traits.read", "traits.write",
"audience_syncs.read",
"destinations.read",
"syncs.read"
]
}'POST returns 201 with the created role. roles.write is required, and Owner and Admin are the built-in roles that carry it.
Three Roles Worth Building
| Role | Permissions to grant | What it gets you |
|---|---|---|
| Data engineer | sources.read, sources.write, connections.read, connections.write, models.read, models.write, loaders.read, loaders.write, warehouse_users.read, warehouse_users.write, warehouse_users.rotate, warehouse_users.use, warehouse_users.delete, execution_environments.read, execution_environments.write, execution_environments.delete | Owns the warehouse side without touching destinations or governance |
| Marketing analyst | audiences.read, audiences.write, traits.read, traits.write, splits.read, splits.write, priority_lists.read, priority_lists.write, models.read, destinations.read, syncs.read | Builds and segments without changing the pipeline underneath |
| Sync operator | syncs.read, syncs.trigger, stores.read, stores.trigger, deletion_rules.read, deletion_rules.execute, models.read, destinations.read | Runs and re-runs the pipeline without being able to redefine it |
Every entry in a role’s permissions array is matched against the catalog exactly, so list the individual keys a category expands to. GET /api/v1/organizations/{orgId}/roles returns the role with the permissions it ended up carrying, which is the quickest way to confirm one reads as you intended.
The separate trigger and execute permissions are what make the third one possible — running a sync is grantable without granting the ability to change what the sync does.
Hiding Customer 360 from a team
Customer 360 shows one customer’s records, so many workspaces keep it to the people who need it. Access to it is its own permission, profiles.read, shown in the role editor as Customer 360 → View. Building audiences and browsing models do not need it.
The built-in Owner, Admin and Member roles all carry it, and built-in roles cannot be edited. To hide Customer 360 from a team:
- Go to Organization settings → Roles and create a role, or Duplicate the role the team has today. Creating, editing and granting roles needs organization administration (
roles.write, carried by Owner and Admin). - Under Data, clear Customer 360 → View.
- Grant the role to the team’s group on the workspace, in place of the role it held. Grants add up, so if the team’s people are also in a group that holds Member or another role with Customer 360 → View, they keep it.
Members of that group no longer see Customer 360 in the navigation or the identity graph’s Explorer tab, cannot open a profile or record link, and the AI agent cannot look up a customer for them. To give it back, tick Customer 360 → View again. The change applies on their next request.
Via the API, remove or add the one key without touching the rest of the role:
curl -X PATCH "$API_BASE_URL/api/v1/organizations/$ORG_ID/roles/$ROLE_ID/permissions" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"remove": ["profiles.read"]}'The same permission covers an identity graph’s Explorer tab, which is hidden without it, and the AI agent’s customer lookups. The rest of the identity graph (its configuration, runs and golden record settings) stays available to anyone with Identity graphs → View.
Editing a Custom Role
Permission changes take effect on the member’s next request. Built-in roles cannot be edited.
curl -X PUT "$API_BASE_URL/api/v1/organizations/$ORG_ID/roles/$ROLE_ID" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Marketing Analyst", "description": "…", "permissions": ["models.read", "audiences.read", "audiences.write"]}'The permissions array replaces the role’s current set rather than adding to it. Leave permissions out to change only the name or description; the role keeps the permissions it has. An empty array removes them all.
To grant or revoke particular permissions without touching the rest, send only the change:
curl -X PATCH "$API_BASE_URL/api/v1/organizations/$ORG_ID/roles/$ROLE_ID/permissions" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"add": ["audiences.write"], "remove": ["syncs.trigger"]}'It returns the role with the permissions it now holds. Prefer it when more than one person or script edits the same role: a PUT sends the whole set as the sender last saw it, so it undoes anything granted in between, while PATCH changes only the keys it names. A key may not appear in both add and remove, and at least one key is required. Adding a key the role already has, or removing one it does not, does nothing. The Organization settings → Roles editor saves every checkbox this way.
Deleting a Custom Role
curl -X DELETE "$API_BASE_URL/api/v1/organizations/$ORG_ID/roles/$ROLE_ID" \
-H "Authorization: Bearer $API_TOKEN"Deleting a role first moves every grant holding it to the built-in Member role, then deletes the role. The reassignment is committed before the delete is issued, so if the delete fails the reassignment stands and the role is still there — re-issue the delete.
This is what stands between a role delete and a silent revocation: the foreign key from a grant to its role is ON DELETE CASCADE, so an unguarded delete would remove the grants instead of the role, taking a whole group’s access to a workspace with no error anywhere.
Rules
- Role names are unique within an organization, compared without regard to case — “Analysts” and “analysts” collide
owner,adminandmemberare reserved and cannot be used as custom role names- Built-in roles cannot be edited or deleted. They belong to no organization, which is what makes the same three ids usable from every one of them
- Custom roles belong to one organization, and can be granted in any of its workspaces
Granting a Role
A role reaches a person through a grant, so changing what somebody can do means changing the grant their group holds — or moving them to a different group.
Via the UI
A workspace’s Workspace settings → Groups tab (Workspace settings is the last item under Governance in the sidebar) lists the groups that reach it, each with an inline roles picker and, for organization administrators, Revoke. From the other end, Organization settings → Groups puts the organization’s groups down the left and the selected one’s workspaces and roles on the right.
Via the API
curl -X PUT "$API_BASE_URL/api/v1/organizations/$ORG_ID/groups/$GROUP_ID/workspaces/$WORKSPACE_ID" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"role_id": "00000000-0000-0000-0000-000000000002"}'role_id accepts any built-in or custom role id, or null — which attaches the group to the workspace and grants it nothing. The built-in ids are stable:
| Role | ID |
|---|---|
| Owner | 00000000-0000-0000-0000-000000000001 |
| Admin | 00000000-0000-0000-0000-000000000002 |
| Member | 00000000-0000-0000-0000-000000000003 |
Granting requires organization administration. The change takes effect on that group’s members’ next request, and is recorded in the workspace audit log under the workspace it affects.
Roles and Access Policies
A role decides which actions a member can take. Access policies decide which rows they see, and are assigned through groups.
Holders of Owner or Admin who are in no group carrying an access policy read every row. Once such a person is assigned a policy through a group, that policy applies to them like anyone else.
Next Steps
- Permissions reference — every key and which role carries it
- Groups — the thing a role is granted to
- Managing members — invite people and carry them into workspaces