> ## 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.

# Calendly

> Learn how to connect Opal to Calendly to review organization membership and invite or remove users.

With the Calendly integration, you can manage who belongs to your Calendly organization from Opal:

* Allow users to request access to Calendly, which invites them to your organization
* Remove users from Calendly when their access is revoked or expires
* Review who holds each organization role, who belongs to each group, and who hosts each event type
* Include Calendly access in [access reviews](https://docs.opal.dev/docs/access-campaigns.md)

Opal connects to one Calendly organization through a personal access token. To manage several organizations, add a Calendly app in Opal for each one.

## Supported resources

| Resource | Read | Grant and revoke access |
| - | - | - |
| Users (members and pending invitations) | ✔️ | ✔️ Invite and remove |
| Organization roles — *Calendly Role* | ✔️ | ✔️ **User** role only |
| Groups — *Calendly Group* | ✔️ | |
| Event types — *Calendly Event Type* | ✔️ | |

### How Calendly access maps to Opal

* **Organization roles**: Opal syncs the **Owner**, **Admin**, and **User** roles. Granting **User** invites the person to your organization by email, and revoking it removes them or cancels their pending invitation. Pending invitees appear as **User** until they accept.
* **Groups**: each Calendly group appears in Opal with the access levels **Member** and **Admin**. Membership is read-only. Manage it in Calendly.
* **Event types**: each event type appears in Opal with its hosts. Event types are read-only and can't be requested.

### Limitations

* Calendly's API can't change a member's role, so Opal can't grant **Owner** or **Admin**, and can't revoke them from someone who holds them. Change these roles in Calendly.
* Opal can't change group membership or event type hosts. Calendly doesn't offer an API to write either.
* Teams are not synced.
* If your organization manages users with SCIM, Calendly rejects invites and removals from Opal. Opal still syncs users, roles, groups, and event types for review.

## Requirements

Before you begin, you must:

* Be an Opal Admin
* Be an Owner or Admin of the Calendly organization
* Be on version `1.1259.0` or later, if you self-host Opal
* Ask the Opal team to enable the Calendly integration for your organization

## Configuration steps

### 1. Create a personal access token

1. In Calendly, go to **Integrations & apps** > **API and webhooks**, and generate a new personal access token.
2. Name the token, for example `Opal`, and select the following scopes:

| Scope | Why |
| - | - |
| `users:read` | Identify the token's organization |
| `organizations:read` | Sync members, roles, and invitations |
| `organizations:write` | Invite and remove users |
| `groups:read` | Sync groups and group membership |
| `event_types:read` | Sync event types and hosts |

3. Copy the token. Calendly shows it once.

> [!WARNING]
>
> The token acts as the person who created it. Create it from an account that will stay an Owner or Admin of the organization. If that person leaves, replace the token before you remove them in Calendly.

### 2. Create the Calendly app in Opal

In Opal, go to **Inventory** > **+ App** and select **Calendly**. Fill in the following fields:

| Field | Value |
| - | - |
| App name | A name for the Calendly app in Opal, for example `Calendly`. |
| App admin | The owner who administers the app in Opal. |
| Description | A short description that helps requesters understand what this app is. |
| Visibility | Who in your organization can see the app. |
| Personal access token | The token from step 1. |

Opal connects to the organization the token belongs to, and checks that it can read users and groups when you save the app.

### 3. Import roles, groups, and event types

On the app's **Assets** tab, select **Import assets** and choose the roles, groups, and event types you want to manage. To let people request Calendly, turn on requests for the **User** role.

## Troubleshooting

| Error | Fix |
| - | - |
| The token could not read the current Calendly user | Check that you copied a personal access token with the `users:read` scope. |
| Cannot read Calendly users or groups | Add the `organizations:read` and `groups:read` scopes, then update the token in Opal. |
| The Calendly token cannot change organization users | Add the `organizations:write` scope, and check that the token's creator is still an Owner or Admin. |
| Calendly is managing users with SCIM | Invite and remove users through your identity provider instead. |
| Calendly's API cannot assign the owner or admin role | Change the role in Calendly. Opal syncs it on the next pull. |


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