Access Groups

What you will learn: This page explains how Access Groups work, how to create and configure groups, how to assign members, and how to use the permission model to control access to ZappWay features.

🔢 Table of Contents

Overview
How Access Groups Work
Endpoint Reference
Managing Groups
Managing Members
System Groups
Permission Audit
Response Format
Best Practices
Troubleshooting

1. Overview

What are Access Groups?

Access Groups are collections of permissions that you assign to team members. Instead of managing individual permissions per person, you:

Create a group (e.g., “Sales Team”, “Support Manager”)
Define its permissions (e.g., read conversations, manage contacts)
Assign members to the group

All members of a group inherit its permissions automatically.

Key Benefits

Simplified management — Change permissions for an entire team at once
Role-based access — Match your organization structure to platform access
Auditable — Every group change is recorded in the permission audit log
Scalable — Works for teams of 2 to 2000+

2. How Access Groups Work

Permission Model

ZappWay uses a permission-based access model with granular permissions such as:

Permission	What it grants
`conversations.read`	View conversations
`conversations.write`	Reply to and manage conversations
`agents.read`	View AI Employees
`agents.write`	Create and edit AI Employees
`contacts.read`	View contacts
`contacts.write`	Create and edit contacts
`groups.read`	View access groups
`groups.manage`	Create, edit, and delete groups
`team.invite`	Invite new team members
`team.change_group`	Move members between groups
`billing.read`	View billing information
`billing.manage`	Manage subscription and payments

Group Assignment Flow

Organization Admin
       ↓
Creates Access Group (with permissions)
       ↓
Invites team member OR changes existing member's group
       ↓
Team member inherits all group permissions
       ↓
Member can access features matching their permissions

3. Endpoint Reference

Method	Endpoint	Description	Auth
`GET`	`/api/access-groups`	List all access groups in the organization	`groups.read` OR `team.invite` OR `team.change_group`
`POST`	`/api/access-groups`	Create a new access group	`groups.manage`
`GET`	`/api/access-groups/[id]`	Get a specific access group	`groups.read`
`PATCH`	`/api/access-groups/[id]`	Update an access group	`groups.manage`
`DELETE`	`/api/access-groups/[id]`	Delete an access group	`groups.manage`
`GET`	`/api/access-groups/[id]/members`	List members of a group	`groups.manage`
`PATCH`	`/api/access-groups/[id]/members`	Assign members to a group	`groups.manage`
`DELETE`	`/api/access-groups/[id]/members`	Reset (remove) members from a group	`groups.manage`

4. Managing Groups

List Access Groups

GET /api/access-groups

Returns all access groups in the current organization, including system-managed groups. Response:

[
  {
    "id": "grp_abc123",
    "organizationId": "org_xyz",
    "key": "sales_team",
    "name": "Sales Team",
    "description": "Access for sales representatives",
    "isSystem": false,
    "permissions": ["conversations.read", "conversations.write", "contacts.read", "contacts.write"],
    "memberCount": 5,
    "createdAt": "2025-01-10T08:00:00.000Z",
    "updatedAt": "2025-01-15T14:00:00.000Z"
  },
  {
    "id": "grp_sys_admin",
    "key": "admin",
    "name": "Administrator",
    "isSystem": true,
    "permissions": ["*"],
    "memberCount": 2
  }
]

Create an Access Group

POST /api/access-groups
Content-Type: application/json

Request Body:

Field	Type	Required	Description
`name`	`string`	✅	Display name of the group
`key`	`string`	❌	Machine-readable key (auto-generated from name)
`description`	`string`	❌	Description of the group’s purpose
`permissions`	`string[]`	✅	Array of permission strings to grant

Example:

{
  "name": "Support Team",
  "description": "Frontline support agents — can read and reply to conversations",
  "permissions": [
    "conversations.read",
    "conversations.write",
    "contacts.read",
    "agents.read"
  ]
}

cURL:

curl -X POST "https://your-domain.com/api/access-groups" \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" \
  -d '{
    "name": "Support Team",
    "permissions": ["conversations.read", "conversations.write", "contacts.read"]
  }'

TypeScript:

const response = await fetch('/api/access-groups', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Support Team',
    description: 'Frontline support agents',
    permissions: ['conversations.read', 'conversations.write', 'contacts.read'],
  }),
});

const group = await response.json();

Every POST and DELETE on access groups is recorded in the permission audit log automatically.

Update an Access Group

PATCH /api/access-groups/{groupId}
Content-Type: application/json

All fields are optional. Only provided fields are updated. Example — add a permission:

{
  "permissions": [
    "conversations.read",
    "conversations.write",
    "contacts.read",
    "contacts.write"
  ]
}

Updating permissions replaces the entire permission set. Always include all desired permissions in the update, not just the additions.

Delete an Access Group

DELETE /api/access-groups/{groupId}

⚠️ System groups cannot be deleted. Attempting to delete a system group (isSystem: true) returns 403 Forbidden.

5. Managing Members

List Members of a Group

GET /api/access-groups/{groupId}/members

Response:

[
  {
    "id": "mem_abc",
    "userId": "user_123",
    "name": "Jane Smith",
    "email": "jane@company.com",
    "role": "member",
    "joinedAt": "2025-01-12T10:00:00.000Z"
  }
]

Assign Members to a Group

PATCH /api/access-groups/{groupId}/members
Content-Type: application/json

Request Body:

Field	Type	Required	Description
`membershipIds`	`string[]`	✅	Array of membership IDs to add to the group

Example:

{
  "membershipIds": ["mem_abc123", "mem_def456"]
}

Remove Members from a Group

DELETE /api/access-groups/{groupId}/members
Content-Type: application/json

Request Body:

{
  "membershipIds": ["mem_abc123"]
}

6. System Groups

ZappWay automatically creates system-managed access groups for every organization:

Group Key	Name	Description
`admin`	Administrator	Full access to all features
`member`	Member	Default access for new team members
`viewer`	Viewer	Read-only access

System group rules:

System groups cannot be deleted
System group permissions cannot be modified (managed by ZappWay)
Every new team member is assigned to member by default unless you specify otherwise during invitation

7. Permission Audit

Every group creation, update, deletion, and member assignment is automatically recorded in the permission audit log. The audit record includes:

Who made the change (user)
What changed (action: create, update, delete)
What resource was affected (access group ID, key)
Outcome (success/failure)
Metadata (group key, whether it’s a system group)

You can export audit logs via the organization settings.

8. Response Format

Status Codes

Status	Meaning
`200`	Request successful
`201`	Group created
`400`	Invalid request body
`401`	Not authenticated
`403`	Insufficient permissions or attempting to modify a system group
`404`	Access group not found in organization
`500`	Internal server error

9. Best Practices

Design Your Group Structure First

Before creating groups, map your organization structure:

Organization
├── Administrator (system group — full access)
├── Team Lead (custom — can invite + change groups)
├── Sales Representative (custom — conversations + contacts)
├── Support Agent (custom — conversations read/write)
└── Viewer (system group — read only)

Permission Assignments

✅ Do:

Follow the principle of least privilege — grant only the permissions each role actually needs
Create role-based groups that match real job functions
Review permissions quarterly and remove unnecessary ones

❌ Avoid:

Creating one group with all permissions for non-admin users
Duplicating the admin system group behavior in custom groups
Giving billing.manage to non-financial team members

Managing Members at Scale

Assign members to groups during invitation rather than after (cleaner workflow)
Use PATCH /members to do bulk reassignments when reorganizing teams
Review group membership after team members change roles

10. Troubleshooting

Problem	Possible Cause	Solution
`403 Forbidden` on group operations	Not enough permissions	You need `groups.manage` permission
Cannot delete system group	The group has `isSystem: true`	System groups cannot be deleted; contact support if you need changes
Member not inheriting group permissions	Cache delay	Wait a few seconds and refresh; session permissions update on next login
Wrong permissions after group update	`permissions` update replaces the full set	Always include all desired permissions in the update payload
Member listed but no access	Member is in multiple groups; another group may restrict access	Check all group memberships for the affected user

Agent Skills

Agent Cortex

Livia - 360 Assistant

Conversations

Access Groups

🔢 Table of Contents

1. Overview

What are Access Groups?

Key Benefits

2. How Access Groups Work

Permission Model

Group Assignment Flow

3. Endpoint Reference

4. Managing Groups

List Access Groups

Create an Access Group

Update an Access Group

Delete an Access Group

5. Managing Members

List Members of a Group

Assign Members to a Group

Remove Members from a Group

6. System Groups

7. Permission Audit

8. Response Format

Status Codes

9. Best Practices

Design Your Group Structure First

Permission Assignments

Managing Members at Scale

10. Troubleshooting

​🔢 Table of Contents

​1. Overview

​What are Access Groups?

​Key Benefits

​2. How Access Groups Work

​Permission Model

​Group Assignment Flow

​3. Endpoint Reference

​4. Managing Groups

​List Access Groups

​Create an Access Group

​Update an Access Group

​Delete an Access Group

​5. Managing Members

​List Members of a Group

​Assign Members to a Group

​Remove Members from a Group

​6. System Groups

​7. Permission Audit

​8. Response Format

​Status Codes

​9. Best Practices

​Design Your Group Structure First

​Permission Assignments

​Managing Members at Scale

​10. Troubleshooting

🔢 Table of Contents

1. Overview

What are Access Groups?

Key Benefits

2. How Access Groups Work

Permission Model

Group Assignment Flow

3. Endpoint Reference

4. Managing Groups

List Access Groups

Create an Access Group

Update an Access Group

Delete an Access Group

5. Managing Members

List Members of a Group

Assign Members to a Group

Remove Members from a Group

6. System Groups

7. Permission Audit

8. Response Format

Status Codes

9. Best Practices

Design Your Group Structure First

Permission Assignments

Managing Members at Scale

10. Troubleshooting