# Connect Twilio

Canonical URL: https://docs.fuse.init.inc/integrations/twilio/setup

Create Twilio API keys and submit Account SID plus API key credentials to Init.



## Before you start [#before-you-start]

Twilio uses **customer API key pair** authentication (HTTP Basic with API Key SID and secret), not a platform OAuth app.

**Connection admin/user** creates credentials in Twilio and submits them through Init Connect. Prefer API keys over the primary Auth Token for production.

You need:

* Access to the Twilio Console for the target Account SID.
* Permission to create API keys in that account (and region, if you use Twilio Regions).

## Configure the provider [#configure-the-provider]

### Create credentials (**Connection admin/user**) [#create-credentials-connection-adminuser]

1. In Twilio Console, open **Account → API keys & auth tokens** (path labels vary slightly between Console versions).
2. Note the **Account SID** (starts with `AC`).
3. Create an API key. Prefer a **Standard** or **Restricted** key with only the Messaging, Voice, or Lookup permissions your Init actions require. Avoid Main keys unless you truly need Accounts/Keys management APIs.
4. Copy the **API Key SID** (starts with `SK`) and the **API Key Secret** when shown. The secret is displayed once.
5. Store the secret in a secret manager. Do not commit it.

There is no Init platform Twilio client registration step.

## Connect to Init [#connect-to-init]

**Connection admin/user** starts a Twilio Connect session and submits these contract fields:

| Field            | Required | Notes                                   |
| ---------------- | -------- | --------------------------------------- |
| `account_sid`    | Yes      | Account SID (`AC` + 32 hex characters). |
| `api_key_sid`    | Yes      | API Key SID (`SK` + 32 hex characters). |
| `api_key_secret` | Yes      | Secret shown once at key creation.      |

Do not paste real SIDs or secrets into documentation. Refer to field names only.

Init authenticates to Twilio with the API Key SID and secret as the Basic-auth username and password for the given Account SID.

## Permissions [#permissions]

Key type controls privilege:

* **Restricted** — least privilege; grant only the Twilio product permissions Init will call.
* **Standard** — broad API access except Accounts/Keys management.
* **Main** — equivalent to Auth Token breadth; avoid for Init unless required.

Match the key’s region to the Account SID region when using Twilio Regions.

## Verify the connection [#verify-the-connection]

1. Complete Connect and confirm the connection is active.
2. Run Init’s connection test or a safe read against a non-production resource (for example a Lookup or account-level read your key allows).
3. Success looks like Twilio accepting Basic auth with the API key and returning a successful read without `20003` authentication failures.

## Rotate or revoke access [#rotate-or-revoke-access]

1. Create a new API key in Twilio.
2. Reconnect in Init with the same `account_sid` and the new `api_key_sid` / `api_key_secret`.
3. Delete the old API key in Twilio Console after the new connection works.

If a secret is exposed, delete the compromised key immediately, then reconnect.

## Troubleshooting [#troubleshooting]

| Symptom                                     | What to check                                                                       |
| ------------------------------------------- | ----------------------------------------------------------------------------------- |
| Connect validation error on SIDs            | `account_sid` must match `AC` + 32 hex; `api_key_sid` must match `SK` + 32 hex.     |
| Authentication failure                      | Confirm secret belongs to that API Key SID and was not truncated.                   |
| Permission errors on Messaging/Voice/Lookup | Restricted key is missing product permissions; create a key with the needed grants. |
| Wrong account                               | Account SID must be the parent account (or correct subaccount) for the key.         |