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

# Notion groups and members

> Learn how to connect Opal to Notion to see workspace members and manage permission group membership.

With the Notion integration, you can manage permission-group membership from Opal:

* See the people in a Notion workspace
* See permission groups and who is in each group
* Let people request to join a group, and remove them when access expires
* Delegate approvals to the right owners

Opal connects to one Notion workspace with one integration token. To manage another workspace, add another Notion app.

This page is the inventory app. Audit tickets and ticket propagation stay on the [Notion ticketing integration](https://docs.opal.dev/integrations/notion.md).

## Supported resources

| Resource | Read | Grant and revoke access | Notes |
| - | - | - | - |
| Users | ✔️ | | Workspace members who have an email address. Guests, bots, and people with no email are not imported. Opal does not invite or remove Notion users. |
| Permission groups | ✔️ | ✔️ | Direct members only. A new member is added as Member. Opal does not assign the Owner role. |

## Requirements

Before you begin, you must:

* Be an Opal Admin
* Be a Notion organization owner. Group sync needs the Enterprise plan
* Be able to create an organization-level admin API token

If you do not see **Notion** under **+ App**, contact Opal support.

> [!WARNING]
>
> A workspace internal integration token can list members, but it cannot read permission groups. Opal treats that failure as a failed sync, so no accounts are imported. Use the organization token below.

## Configuration steps

### 1. Create an organization token

1. In Notion, open the workspace switcher and select **Manage organization**.
2. Go to **General**, then **Manage organization-level admin API tokens**.
3. Select **Create connection**. Name it, for example `Opal`.
4. Give the connection these scopes:

| Scope | Why Opal needs it |
| - | - |
| `permission-group:read` | List groups and their members |
| `permission-group:write` | Add and remove group members |

5. Select **Create token** and copy the token. Store it where your team keeps secrets.

The `permission-group` scopes appear [only for eligible Enterprise organizations](https://www.notion.com/help/admin-apis-for-enterprise-organizations). If they are missing, contact your Notion representative.

The same token is also used to list workspace members. People without an email address are skipped.

### 2. Create a Notion app in Opal

In Opal, go to **Inventory** > **+ App**, then select **Notion**.

Fill in the following fields and create the app.

| Field | Value |
| - | - |
| App name | An identifiable name for this Notion workspace. |
| App admin | The team or user that should own the Notion app in Opal. |
| Description | Let requesters know what they are requesting access to. |
| Visibility | Global, or restricted to specific groups. |
| Integration token | The organization token from step 1. |

Opal reads the workspace from the token. You do not enter a workspace ID.

Saving the app again with the same token restores the existing app. A different token is a different app, even for the same workspace.

### 3. Confirm the sync

After you create the app, Opal syncs members onto the **Accounts** tab and permission groups onto the **Groups** tab.

Turn on requests for the groups people should be able to ask for. A request adds the person as a Member. When the grant is revoked or expires, Opal removes them from the group.

## Groups

* **Already a member:** Opal leaves them as they are, including group Owners. It does not change their role.
* **Not a member:** Opal adds them as a Member. Restricted members can be added as members. Notion does not allow guests in a permission group.
* **Remove:** Opal removes them from the group. This includes group Owners. Opal cannot grant the Owner role.
* **SCIM:** If your identity provider manages the group's membership, Notion rejects the change. Update that group in the identity provider.
* **Nested groups:** Opal syncs direct user members only. Membership that comes from a group inside a group is not listed.

## What Opal does not manage

* Inviting, creating, or removing Notion users
* Guests
* The Owner role inside a group
* Groups whose membership is managed by SCIM
* Nested groups
* Access to pages, databases, and teamspaces
* Audit tickets and ticket propagation. Those stay on the existing [Notion ticketing integration](https://docs.opal.dev/integrations/notion.md).

## Troubleshooting

| What you see | What to do |
| - | - |
| Notion is not in **+ App** | Contact Opal support and ask them to enable the Notion integration. |
| The sync fails and no accounts are imported | The token cannot read groups. Use an Enterprise organization token with both `permission-group:read` and `permission-group:write`. |
| A person is missing from Accounts | Notion's user list omits guests. Opal also skips bots and anyone with no email address. |
| Adding or removing a group member fails | The group may be managed by your identity provider. Change that membership there. Guests cannot be added to a permission group. |
| A second Notion app appeared for the same workspace | Each token is its own app. Keep one token for the workspace. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.