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

# Twilio

## After this article

You'll be able to connect Twilio to Lumos to bring in Twilio subaccounts for visibility, Access Reviews, and offboarding, including suspending and deprovisioning them directly from Lumos.

## Capabilities

The Twilio API does not support reading users, so Lumos brings in **subaccounts** instead. This is why user accounts may not appear the way you expect.

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users (subaccounts) | Account | Yes | Yes | Reads Twilio subaccounts, last activity, and entitlements. Suspend and deprovision supported (see below) |

| AppStore | Offboarding | Access Reviews | License Management |
| - | - | - | - |
| No | Yes | Yes | Yes |

**Status mapping:** Twilio `active` maps to **Active**, `suspended` maps to **Suspended**, and `closed` maps to **Deprovisioned**.

**Last activity** is the last time the user did a cost-incurring activity. Lumos reads the user's usage records and uses the `end_date` of the most recent record that has a non-null, non-zero price.

**Entitlements** Lumos retrieves:

* **Account Type**, a role showing whether a Twilio account is a Trial account or an upgraded Full account.
* **Account Services**, a role showing the services an account has used, such as Verify and Task Router. The Account Services last activity is the most recent `end_date` across that service's cost-incurring usage records.

| Deprovisioning Action | Type | Description |
| - | - | - |
| Suspend | User | Suspends the subaccount tied to the user. Suspended subaccounts cannot make or receive phone calls and cannot send or receive SMS. If a subaccount owns phone numbers, the owning account keeps being charged monthly for them |
| Deprovision | User | Permanently closes the subaccount tied to the user. Twilio deletes the subaccount after thirty days |

A user tied to the account you used to connect the integration cannot be suspended or deprovisioned.

## Required plan and roles

* **Twilio plan:** no plan is required to use the Twilio integration. Even trial accounts can connect to Lumos.
* **API key type:** Lumos only supports connecting with API keys from Twilio **accounts**, not Twilio subaccounts. The key must be a **Main** API key. Standard and restricted API keys are not supported.

## Read-only access vs provisioning

**Is read-only possible?** No. Lumos only supports Main API keys on Twilio accounts, and standard or restricted (narrower-scoped) API keys aren't supported, so there's no way to create a key that limits Lumos to read-only.

**What full provisioning requires.** The same Main API key used to connect, paired with the Account SID. That one credential is what Lumos uses both to read subaccounts and to suspend or close them, so no separate credential unlocks offboarding.

**Watch out for.** A user tied to the account you used to connect can't be suspended or deprovisioned. Deprovisioning permanently closes the subaccount, and Twilio deletes it after thirty days, so it can't be undone once queued.

## Instructions

**Phase 1: Gather credentials in Twilio**

1. Log in to Twilio.
2. On the Twilio homepage, go to the top left and select the account you want to connect to Lumos.
3. Go to the bottom of the accounts page and copy the **Account SID**. You'll use this for the Account SID value in Lumos.
4. Go to the top right of the accounts page, click the **Account** dropdown, then open **API Keys & Tokens**.
5. Click **Create API Key**.
6. In the **Key Type** dropdown, select **Main**. Give the key an identifiable Friendly Name, such as "Lumos Main API Key."
7. Click **Create**. Twilio redirects you to a **Copy Secret Key** page.
8. Copy the **SID** and the **Secret**. The SID is your API Key SID in Lumos and the Secret is your API Key Secret in Lumos.

**Phase 2: Connect in Lumos**

1. Find the Twilio card in your Lumos integrations (reconnect an existing card or add a new one).
2. Paste your Account SID into the **Account SID** field.
3. Paste your API Key SID into the **API Key SID** field.
4. Paste your API Key Secret into the **API Key Secret** field.
5. Click **Connect Twilio**.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**No users populate after connecting.** The Twilio API does not support reading users, so Lumos reads subaccounts instead. Confirm your Twilio account has subaccounts to bring in.

**A subaccount cannot be suspended or deprovisioned.** A user tied to the account you used to connect the integration is excluded from both actions. Use a different connecting account if you need to act on that subaccount.

**Connection fails when saving credentials.** Confirm you created a **Main** API key on a Twilio account rather than a subaccount, and that you pasted the Account SID, API Key SID, and API Key Secret into their matching fields.