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

# Twilio

> Learn how to connect Opal to Twilio to manage organization roles and managed users.

With the Twilio integration, you can manage access to your Twilio organization from Opal:

* See the managed users in the organization
* Allow users to request an organization role, such as **Organization Admin** or **Standard User**, from the web and Slack
* Create a managed user, and deactivate them when they should no longer have access
* Set the right resource owners to delegate approvals to those with the most context
* Automatically revoke a role when a time-bound grant expires

Opal connects to one Twilio organization through an Organization OAuth app. To manage several organizations, add a Twilio app in Opal for each one.

## Supported resources

| Resource | Read | Grant and revoke access |
| - | - | - |
| Twilio Organization | ✔️ | ✔️ (not **Organization Owner**) |
| Managed users | ✔️ | Create and deactivate |

A person can hold more than one organization role. Granting a role adds that role. Revoking a role removes only that role.

### How Twilio access maps to Opal

* **Twilio Organization** is the only resource. Its access levels are the roles Twilio accepts on the organization.
* **Organization Owner** is synced, but Opal doesn't grant or revoke it. Change ownership in the Twilio Console.
* Account-only roles, such as **Developer** and **Billing Manager**, are not offered. Twilio refuses them on the organization.
* **Billing Group Admin** and **Billing Group Viewer** are not offered. Those roles belong on one billing group, and Twilio doesn't provide a way to list billing groups.

### Limitations

* Opal doesn't sync accounts, subaccounts, or the roles that apply only to an account.
* Opal doesn't sync billing groups.
* Opal doesn't change a user's name or email, and it doesn't suspend a user. Deactivating a user is the only removal.
* Opal doesn't deactivate the Organization Owner.

## Requirements

Before you begin, you must:

* Be an Opal Admin
* Be a Twilio Organization Owner or Organization Admin. Those are the roles that can create an Organization OAuth app.
* Have a Twilio organization. The Organization SID starts with `OR` and is on **Settings** > **Organization settings** > **Organization details**. If the account has no organization yet, [create one](https://www.twilio.com/docs/iam/organizations) first.
* Ask the Opal team to enable the Twilio integration for your organization

## Configuration steps

### 1. Create an Organization OAuth app

Twilio's organization APIs accept only OAuth 2.0. An account SID with an Auth Token or API key can't be used. Use the **Client credentials** grant, which is for server-to-server access. Twilio's steps are in [Organization OAuth apps](https://www.twilio.com/docs/iam/oauth-apps/org-oauth-apps).

1. In the Twilio Console, go to **Settings** > **Organization settings** > **Organization API access**.
2. Select **Create OAuth application**.
3. For **Grant type**, select **Client credentials**.
4. Name the application, for example `Opal`, and add a short description.
5. On **Scopes & permissions**, select the following permissions:

| Permission | Why Opal needs it |
| - | - |
| `managed-users/list` | Sync people |
| `managed-users/create` | Create a managed user |
| `managed-users/update` | Turn a deactivated user back on |
| `managed-users/delete` | Deactivate a user |
| `roles/list` | Sync the roles that can be granted |
| `role-assignments/list` | Sync who holds each role |
| `role-assignments/create` | Grant a role |
| `role-assignments/delete` | Revoke a role |

6. On the **Copy secret** page, copy the Client ID and Client secret and store them where your team keeps secrets. Select **Got it!**, then **Finish**.

You can rotate the client secret later from the application's **Credentials** tab. After you rotate it, update the secret on the Twilio app in Opal.

### 2. Create the Twilio app in Opal

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

| Field | Value |
| - | - |
| App name | A name for the Twilio app in Opal, for example `Twilio`. |
| 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. |
| Organization SID | The SID from Organization details. It starts with `OR`. |
| Client ID | The Client ID from step 1. |
| Client secret | The Client secret from step 1. |

Opal checks the Organization SID and the OAuth app when you save. A SID from a different organization, or a client secret that doesn't match the Client ID, is rejected.

### 3. Import the organization

After you save the app, on the app's **Assets** tab, select **Import assets**, choose **Twilio Organization**, and turn on requests for the roles people should be able to ask for.

Opal pulls users and role assignments only for imported items. Managed users show on the **Accounts** tab. Who holds each role shows on **Twilio Organization** after the next sync.

The app's **Setup** tab lists the reads this OAuth app must be allowed to make. A failed check names the permission to add.

## Users

* **Create.** Opal creates a managed user from their email address. Twilio only accepts an email on a domain the organization has verified, and emails the new user a link to set a password.
* **Deactivate.** Removing the user in Opal deactivates them in Twilio. Twilio keeps the user.
* **Turn back on.** Creating a user whose email matches a deactivated user turns that same user back on.
* **Organization Owner.** Opal doesn't deactivate the Organization Owner. Change ownership in the Twilio Console.

## Troubleshooting

| What you see | What to do |
| - | - |
| Twilio is not under **+ App** | Ask the Opal team to enable the Twilio integration. |
| Saving the app fails on the client secret | Create the OAuth app with grant type **Client credentials**, then copy the Client ID and Client secret again. |
| Saving the app says the organization scope must match | Use the Organization SID from **Organization details**. It starts with `OR`. |
| **Read managed users** fails on the Setup tab | Add `managed-users/list` to the OAuth app, then run the check again. |
| **Read organization roles** or **Read role assignments** fails on the Setup tab | Add `roles/list` or `role-assignments/list`, then run the check again. |
| Creating a user fails because the email domain is not verified | Verify that email domain for the organization in Twilio, then create the user again. |
| Granting or revoking **Organization Owner** fails | Change organization ownership in the Twilio Console. Opal doesn't grant or revoke that role. |
| A role such as **Developer** is missing | That role applies to an account, not the organization. Opal doesn't sync accounts. |


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