> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bizzyco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles & Permissions

> Understand how access control works in Bizzy

Bizzy uses a role-based access control system to manage what team members can
see and do within your organization. This guide explains the permission model
and how to configure access for your team.

## Role Types

Every organization member has one of three roles:

| Role      | Description                                                                                                                                                             |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner** | Full access to all organization resources and settings. Can manage billing, API keys, and delete the organization.                                                      |
| **Admin** | Full access to business data. Can invite members and manage integrations. Can view billing and subscription data but cannot modify the subscription or manage API keys. |
| **User**  | Read-only access to business data (contacts, messages, automations). Full access to their own user resources (files, preferences). Cannot access organization settings. |

<Note>
  Each organization must have at least one Owner. Ownership can be transferred
  but not removed entirely.
</Note>

## Permission Model

Bizzy's permission system is built on three core concepts:

### 1. Actions

Every permission check evaluates one of three actions:

| Action   | HTTP Methods     | Description                |
| -------- | ---------------- | -------------------------- |
| `read`   | GET              | View resources             |
| `write`  | POST, PUT, PATCH | Create or modify resources |
| `delete` | DELETE           | Remove resources           |

### 2. Resources

Resources are organized hierarchically using dot notation. For example:

```
contacts
contacts.emails
contacts.phones
contacts.tags
```

### 3. Inheritance

Permissions flow from parent to child resources. If you grant `read` access to
`contacts`, that permission automatically applies to `contacts.emails`,
`contacts.phones`, and all other child resources—unless explicitly overridden.

## Role Permissions

### Owner Permissions

Owners have unrestricted access to all resources:

| Resource Category      | Read | Write | Delete |
| ---------------------- | ---- | ----- | ------ |
| Organization settings  | Yes  | Yes   | Yes    |
| Members & invites      | Yes  | Yes   | Yes    |
| API keys               | Yes  | Yes   | Yes    |
| Billing & subscription | Yes  | Yes   | Yes    |
| All business data      | Yes  | Yes   | Yes    |

### Admin Permissions

Admins have full data access with limited administrative capabilities:

| Resource Category      | Read | Write | Delete |
| ---------------------- | ---- | ----- | ------ |
| Organization settings  | Yes  | No    | No     |
| Members                | Yes  | No    | No     |
| Invites                | Yes  | Yes   | Yes    |
| Connections            | Yes  | No    | No     |
| Workflows              | Yes  | Yes   | Yes    |
| API keys               | No   | No    | No     |
| Billing & subscription | Yes  | No    | No     |
| Contacts & customers   | Yes  | Yes   | Yes    |
| Messages               | Yes  | Yes   | Yes    |
| Automations            | Yes  | Yes   | Yes    |
| Files & folders        | Yes  | Yes   | Yes    |

### User Permissions

Users have read-only access to organization data with full control over their
own resources:

| Resource Category                        | Read | Write | Delete |
| ---------------------------------------- | ---- | ----- | ------ |
| Organization settings                    | No   | No    | No     |
| Members & invites                        | No   | No    | No     |
| API keys                                 | No   | No    | No     |
| Contacts, customers, businesses, domains | Yes  | No    | No     |
| Messages, automations, email templates   | Yes  | No    | No     |
| Tasks                                    | Yes  | No    | No     |
| RAG resources & embeddings               | Yes  | No    | No     |
| Files & folders                          | Yes  | Yes   | No     |
| Own user profile                         | Yes  | Yes   | Yes    |
| Own notifications                        | Yes  | Yes   | Yes    |

## Resource Categories

The permission system covers these top-level resources:

### Contact and customer data

* `contacts` — Contact records (children: `emails`, `phones`, `addresses`)
* `customers` — Customer relationships (children: `transactions`)
* `businesses` — Business entities (children: `offerings`, `onlinePresences`,
  `physicalPresences`, `profiles`)
* `domains` — Verified and registered domains (children: `domainContacts`,
  `domainRegistrations`)

### Communication

* `messages` — Conversation threads (children: `attachments`, `contacts`)
* `incomingMessages` — Inbound message records (children: `attachments`,
  `contacts`)
* `outgoingMessages` — Outbound message records (children: `attachments`,
  `contacts`)
* `emailTemplates` — Reusable email templates

### Tasks and automations

* `tasks` — Tasks (children: `assignees`, `activity`)
* `automations` — Plain-English automations

### Files and knowledge

* `files`, `folders` — Uploaded files and the folder tree
* `resources`, `embeddings` — RAG-indexed assets used by agents

### Organization administration

* `organization` — Org-level settings, with children:
  * `members` — Team membership
  * `invites` — Pending invitations
  * `connections` — Integration connections (Stripe, etc.)
  * `subscriptions` — Billing and subscription
  * `workflows` — Internal workflow registry
  * `apiKeys` — Owner-only API key management

### User-level resources

* `userNotifications` — Personal notification preferences and history
* `userProfiles` — Personal profile (name, avatar, timezone, language)

## API Key Permissions

API keys have their own independent permission system — they do **not** inherit
the permissions of the user that created them. When you create a key, you grant
it specific resource access and restrict it to specific actions.

This means a User-role team member can still create an API key with broader
permissions than they themselves have, provided their role allows key creation
in the first place (currently Owner-only).

See [API Key Management](/admin-guide/security/api-keys) for details.

## Best Practices

### Principle of Least Privilege

Assign the minimum role needed for each team member:

* Use **User** role for team members who only need to view data
* Use **Admin** role for managers who need to edit data and invite members
* Reserve **Owner** role for account administrators

### Regular Access Reviews

Periodically review your organization's members:

* Remove inactive members promptly
* Verify role assignments match current responsibilities
* Check for any unused API keys

### Separation of Duties

For sensitive operations, consider:

* Limiting Owner role to 1-2 trusted administrators
* Using separate API keys for different integrations
* Enabling audit logging to track changes

## Next Steps

<CardGroup cols={2}>
  <Card title="User Management" icon="users" href="/admin-guide/organization/users">
    Learn how to invite and manage team members
  </Card>

  <Card title="API Keys" icon="key" href="/admin-guide/security/api-keys">
    Create API keys with custom permissions
  </Card>
</CardGroup>