Groups

Groups organize workspace members into logical teams. A group can grant additional permissions to its members and control what data they can see. Instead of managing access filters and permission grants for each member individually, you create groups and add members to them — every member automatically inherits the group’s permissions and access filter assignments.

What Groups Do

Groups serve two purposes in Zeotap:

1. Grant additional permissions — You can assign a role to a group and/or grant specific permissions directly. Every member of the group inherits those permissions in addition to their own role’s permissions. This lets you extend permissions for specific teams without changing individual roles.

2. Control data visibility — Groups are the assignment target for access filters. When an access filter is assigned to a group, every member of that group has their queries automatically filtered.

Permission grants from groups are additive — they can only give members more permissions, never fewer. A member’s effective permissions are the union of:

• Permissions from their assigned role
• Permissions from all group roles they inherit
• All direct permissions from their groups

Creating a Group

Via the UI

1. Navigate to Govern > RBAC > Groups
2. Click Create Group
3. Fill in the group details:

4. Click Create

Via the API

curl -X POST https://your-workspace.zeotap.dev/api/v1/workspaces/{workspace_id}/groups \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EMEA Marketing Team",
    "description": "Members of the marketing team in EMEA region",
    "role_id": "role-uuid-here"
  }'

The role_id field is optional. Omit it to create a group without a role assignment.

Response:

{
  "id": "grp_abc123",
  "name": "EMEA Marketing Team",
  "description": "Members of the marketing team in EMEA region",
  "role_id": "role-uuid-here",
  "member_count": 0,
  "subset_count": 0,
  "created_at": "2025-01-15T10:00:00Z"
}

Granting Permissions via Groups

Groups can grant permissions to their members in two ways:

Assigning a Role to a Group

You can assign any built-in or custom role to a group. All members of the group inherit the permissions of that role, in addition to their own role’s permissions.

Via the UI

1. Navigate to the group detail page
2. In the Group role dropdown, select a role
3. Click Save changes

Via the API

curl -X PUT https://your-workspace.zeotap.dev/api/v1/workspaces/{workspace_id}/groups/{group_id} \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data Team",
    "description": "Data engineering team",
    "role_id": "role-uuid-here"
  }'

Set role_id to null to remove the group’s role assignment.

Granting Direct Permissions

For finer-grained control, you can grant specific permissions directly to a group without assigning a full role. This is useful when a team needs a specific set of permissions that does not match any existing role.

Via the UI

1. Navigate to the group detail page
2. In the Direct permissions section, click Edit
3. Check the permissions you want to grant, organized by category
4. Click Save

Via the API

# View current direct permissions
curl https://your-workspace.zeotap.dev/api/v1/workspaces/{workspace_id}/groups/{group_id}/permissions \
  -H "Authorization: Bearer $API_TOKEN"
 
# Set direct permissions
curl -X PUT https://your-workspace.zeotap.dev/api/v1/workspaces/{workspace_id}/groups/{group_id}/permissions \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["syncs.read", "syncs.trigger", "destinations.read"]
  }'

Combining Role and Direct Permissions

A group can have both a role assignment and direct permissions. The effective permissions granted by the group are the union of:

• All permissions from the assigned role
• All direct permissions

This allows you to start with a role as a base and add specific extra permissions as needed.

Managing Group Members

Adding Members

Via the UI

1. Navigate to Govern > RBAC > Groups
2. Click on the group
3. In the Members tab, click Add Members
4. Select workspace members from the list (search by name or email)
5. Click Add

Via the API

curl -X POST https://your-workspace.zeotap.dev/api/v1/workspaces/{workspace_id}/groups/{group_id}/members \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "member_ids": ["mem_abc123", "mem_def456"]
  }'

Removing Members

Via the UI

1. Navigate to the group detail page
2. In the Members tab, find the member
3. Click Remove next to their name
4. Confirm the removal

Via the API

curl -X DELETE https://your-workspace.zeotap.dev/api/v1/workspaces/{workspace_id}/groups/{group_id}/members/{member_id} \
  -H "Authorization: Bearer $API_TOKEN"

Member Limitations

• A member can belong to multiple groups. Their effective permissions and data access are the combination of all groups they belong to.
• Adding or removing a member from a group takes effect immediately. Their next request will reflect the updated permissions and access filters.
• Only Owners and Admins (users with governance.manage permission) can modify group membership.

Assigning Access Filters to Groups

Access Filters provide the row-level filtering that groups enforce. See Access Filters for how to create access filters.

Via the UI

1. Navigate to the group detail page
2. In the Access Filters tab, click Add Access Filter
3. Select one or more access filters from the list (grouped by category)
4. Click Save

Via the API

curl -X PUT https://your-workspace.zeotap.dev/api/v1/workspaces/{workspace_id}/groups/{group_id} \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subset_ids": ["sub_abc123", "sub_def456"]
  }'

How Multiple Access Filters Interact

When a group has multiple access filters:

• Access filters in the same category are combined with OR (the member sees data matching any of them)
• Access filters in different categories are combined with AND (the member sees data matching all categories)

See Access Filters for detailed examples.

Viewing Group Details

The group detail page shows:

Editing a Group

To update a group’s name, description, role, or direct permissions:

1. Navigate to the group detail page
2. Click Edit in the header
3. Modify the fields as needed
4. Click Save

Changing a group’s name or description does not affect its members, role assignment, or access filter assignments.

Deleting a Group

To delete a group:

1. Navigate to the group detail page
2. Click Delete
3. Confirm the deletion

Deleting a group:

• Removes all members from the group (their workspace access is not affected)
• Removes all access filter assignments from the group
• Removes all direct permission grants associated with the group
• Members who were in the group will no longer inherit the group’s role or direct permissions

This action cannot be undone.

Common Group Patterns

API Reference

# List all groups
GET /api/v1/workspaces/{id}/groups
 
# Get a single group
GET /api/v1/workspaces/{id}/groups/{groupId}
 
# Create a group
POST /api/v1/workspaces/{id}/groups
 
# Update a group
PUT /api/v1/workspaces/{id}/groups/{groupId}
 
# Delete a group
DELETE /api/v1/workspaces/{id}/groups/{groupId}
 
# Add members to a group
POST /api/v1/workspaces/{id}/groups/{groupId}/members
 
# Remove a member from a group
DELETE /api/v1/workspaces/{id}/groups/{groupId}/members/{member_id}
 
# List group members
GET /api/v1/workspaces/{id}/groups/{groupId}/members
 
# Group Permissions
GET /api/v1/workspaces/{id}/groups/{groupId}/permissions
PUT /api/v1/workspaces/{id}/groups/{groupId}/permissions

Best Practices

• Name groups by team and function — Use descriptive names like “EMEA Marketing” or “Partner Support - Acme” so membership is self-explanatory.
• Keep groups focused — Each group should represent a single team or access pattern. If members need different permissions or data access for different use cases, use separate groups.
• Use role assignment for broad capabilities — Assign a role to a group when an entire team needs the same capability set (e.g., all members of the data team can manage syncs).
• Use direct permissions for surgical grants — Grant direct permissions when a team needs a small number of extra permissions that do not warrant a full role.
• A member can belong to multiple groups — Use this to build composite access. For example, a member in both “EMEA Team” and “Marketing Team” sees EMEA marketing data and inherits permissions from both groups.
• Review membership regularly — As team composition changes, update group membership to ensure data access and permissions stay current.
• Prefer groups over direct management — Even for a single member who needs a unique access filter or permission, create a group. It makes the access model consistent and easier to audit.

Next Steps

• Create access filters to assign to your groups
• Manage workspace members
• Review the permission model to understand role-based access
• Create custom roles to assign to groups