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

# Scoped Access

> Restrict Zoom integration to specific users with custom roles and service accounts

<Tabs>
  <Tab title="Setup">
    <Card title="When to Use This" icon="lock">
      By default, Server-to-Server OAuth apps have access to **all users** in your Zoom account. Use custom roles and scopes to restrict Parable's access to specific teams or departments.
    </Card>

    ## Overview

    This guide walks you through creating a restricted Zoom integration that can only access data for a defined subset of users. The approach involves four steps:

    <CardGroup cols={2}>
      <Card title="1. User Group" icon="users">
        Group the users Parable should access
      </Card>

      <Card title="2. Custom Role" icon="user-shield">
        Create a role scoped to that group
      </Card>

      <Card title="3. Service Account" icon="robot">
        Create a dedicated service user
      </Card>

      <Card title="4. OAuth App" icon="key">
        Create the app as the service user
      </Card>
    </CardGroup>

    <Info>
      **Prerequisite:** This guide assumes familiarity with the standard [Server-to-Server OAuth setup](/connectors/zoom/workplace/server-to-server/setup). You'll create a new, restricted app rather than modifying an existing one.
    </Info>

    ## Setup Guide

    <Steps>
      <Step title="Create a User Group">
        1. Sign in to [Zoom](https://zoom.us) as an account owner or admin
        2. Go to **User Management** → **Groups**
        3. Click **Add Group**

        | Field       | Value                                |
        | ----------- | ------------------------------------ |
        | Group Name  | `Parable-Accessible-Users`           |
        | Description | Users visible to Parable integration |

        4. Click **Add**
        5. Navigate to **User Management** → **Users**
        6. Add target users to the new group
      </Step>

      <Step title="Create a Custom Role">
        1. Go to **User Management** → **Roles**
        2. Click **Add Role**

        | Field       | Value                                 |
        | ----------- | ------------------------------------- |
        | Role Name   | `Parable-Restricted-Role`             |
        | Description | Scoped access for Parable integration |

        3. Go to **Role Settings** tab
        4. Enable the permissions your integration needs:

        | Permission            | Purpose                   |
        | --------------------- | ------------------------- |
        | **Users** (View)      | Read user profiles        |
        | **Dashboard** (View)  | Meeting/webinar data      |
        | **Recording** (View)  | Access recordings         |
        | **Zoom Phone** (View) | Call logs (if applicable) |

        5. **Set the scope for each permission:**
           * Click **Edit** in the **Scope** column
           * Select **Custom Scope**
           * Choose the `Parable-Accessible-Users` group
           * Click **Save**

        <Warning>
          You must set the scope individually for each permission you enable.
        </Warning>
      </Step>

      <Step title="Create a Service Account">
        1. Go to **User Management** → **Users**
        2. Click **Add Users**
        3. Create a dedicated service user:

        | Field     | Value                              |
        | --------- | ---------------------------------- |
        | Email     | `parable-service@yourcompany.com`  |
        | User Type | Licensed (required for phone data) |

        4. Find the new user in the list
        5. Click **Edit** next to their name
        6. Set **User Role** to `Parable-Restricted-Role`
        7. Click **Save**

        <Info>
          The service user must have appropriate licenses to access the data types you need (e.g., Zoom Phone license for call logs).
        </Info>
      </Step>

      <Step title="Create the Server-to-Server OAuth App">
        <Warning>
          You must log in as the **service user** to create the app. Log out of your admin account first.
        </Warning>

        1. Log in to [Zoom App Marketplace](https://marketplace.zoom.us) as `parable-service@yourcompany.com`
        2. Click **Develop** → **Build App**
        3. Select **Server-to-Server OAuth** → **Create**
        4. Name the app: `Parable Restricted Integration`
        5. Go to **Scopes** and add scopes matching your role permissions:

        | Scope                                                                              | Maps to Role Permission                     |
        | ---------------------------------------------------------------------------------- | ------------------------------------------- |
        | `user:read:user`, `user:read:list_users:admin`                                     | Users (View)                                |
        | `meeting:read:meeting`, `meeting:read:list_meetings:admin`                         | Dashboard (View)                            |
        | `meeting:read:list_past_participants`, `meeting:read:list_past_participants:admin` | Dashboard (View) / meeting participants tap |
        | `report:read:admin`, `report:read:user:admin`                                      | Dashboard (View)                            |
        | `team:read:team`, `team:read:list_teams:admin`                                     | Teams (View)                                |
        | `phone:read:admin`, `phone_call_log:read:admin`                                    | Zoom Phone (View)                           |

        6. Complete required fields and **Activate** the app
        7. Copy your credentials from **App Credentials**:
           * Account ID
           * Client ID
           * Client Secret
      </Step>
    </Steps>
  </Tab>

  <Tab title="Reference">
    ## How It Works

    The restriction works through inheritance:

    ```
    Custom Role (scoped to group)
         ↓
    Service User (assigned role)
         ↓
    OAuth App (created by service user)
         ↓
    API Access (inherits role scope)
    ```

    The app credentials inherit the service user's role limitations — the app can only see users within the designated group.

    ## Scopes Quick Reference

    | Data Type            | Required Scopes                                                                    |
    | -------------------- | ---------------------------------------------------------------------------------- |
    | User information     | `user:read:user`, `user:read:list_users:admin`                                     |
    | Meetings             | `meeting:read:meeting`, `meeting:read:list_meetings:admin`                         |
    | Meeting participants | `meeting:read:list_past_participants`, `meeting:read:list_past_participants:admin` |
    | Reports              | `report:read:admin`, `report:read:user:admin`                                      |
    | Teams                | `team:read:team`, `team:read:list_teams:admin`                                     |
    | Phone calls          | `phone:read:admin`, `phone_call_log:read:admin`, `phone:read`                      |

    ## Managing Access

    ### Adding Users

    Simply add users to the `Parable-Accessible-Users` group. No app changes needed.

    ### Removing Users

    Remove users from the group. API access is revoked immediately.

    ### Expanding Permissions

    1. Edit the custom role to add new permissions
    2. Set the scope to your user group
    3. Add corresponding scopes to the OAuth app
    4. Reactivate the app

    ## Troubleshooting

    | Issue                     | Solution                                     |
    | ------------------------- | -------------------------------------------- |
    | App returns no data       | Verify app is activated and scopes are added |
    | Missing users in results  | Check user is in the scoped group            |
    | Phone data unavailable    | Service user needs Zoom Phone license        |
    | Can't create custom scope | Ensure you have admin/owner role             |

    <Accordion title="Common Issues">
      ### "Permission denied" errors

      The OAuth app scopes must match the role permissions. If you enabled "Dashboard (View)" in the role, add the corresponding `meeting:read:*` scopes to the app.

      ### Service user can't access Marketplace

      The service user needs to be a licensed user (not basic) to create Server-to-Server OAuth apps.
    </Accordion>

    ## Additional Resources

    <CardGroup cols={2}>
      <Card title="Zoom Role Management" icon="book" href="https://support.zoom.com/hc/en/article?id=zm_kb&sysparm_article=KB0068636">
        Official role management guide
      </Card>

      <Card title="S2S OAuth Guide" icon="key" href="https://developers.zoom.us/docs/internal-apps/s2s-oauth/">
        Server-to-Server OAuth documentation
      </Card>
    </CardGroup>
  </Tab>
</Tabs>