twilio-admin

What this skill does

# twilio-admin

## Purpose

Enable reliable, auditable administration of Twilio accounts in production:

- Create, configure, suspend, and close subaccounts safely (with guardrails and rollback).
- Monitor usage/costs across parent + subaccounts; detect anomalies; enforce budgets.
- Manage phone numbers at scale (buy/release/port/assign to Messaging Services/Voice apps).
- Maintain compliance posture: SHAKEN/STIR, A2P 10DLC, Toll-Free verification, TrustHub bundles, audit logs.
- Provide repeatable operational workflows (CLI + API) suitable for CI/CD and on-call runbooks.

This skill is for engineers who need deterministic, scriptable control over Twilio admin surfaces without breaking production traffic.

---

## Prerequisites

### Twilio account + permissions

- A Twilio **parent account** with permission to:
  - Create/manage subaccounts
  - View usage records
  - Manage phone numbers
  - Access TrustHub / A2P / Toll-Free verification (as applicable)
- You must have:
  - `ACCOUNT_SID` (starts with `AC...`)
  - `AUTH_TOKEN`
- For subaccount operations, you need each subaccount SID (`AC...`) and (optionally) its auth token if using per-subaccount credentials.

### Supported tooling versions (pinned)

- **twilio-cli**: `5.6.0`
- **Node.js** (for twilio-cli runtime): `20.11.1` (LTS)
- **Python** (for admin scripts): `3.11.8`
- **twilio-python**: `9.4.1`
- **jq**: `1.7`
- **curl**: `8.5.0`
- **OpenSSL**: `3.0.13` (for TLS inspection / cert tooling)
- **Docker** (optional for hermetic runs): `25.0.3`

### OS support

- Ubuntu `22.04` / `24.04`
- Fedora `39` / `40`
- macOS `14` (Sonoma) on Intel + Apple Silicon

### Auth setup (recommended patterns)

1. **Local dev**: Twilio CLI profile + environment variables.
2. **CI**: short-lived secrets from a vault (AWS Secrets Manager / GCP Secret Manager / Vault) injected as env vars.
3. **Production automation**: separate Twilio API keys (where applicable) and strict scoping; avoid using the primary Auth Token in CI.

> Note: Twilio’s classic model uses Account SID + Auth Token. Some products support API Keys; for admin operations, you often still need Account SID + Auth Token. Treat Auth Token as a root secret.

---

## Core Concepts

### Parent account vs subaccounts

- **Parent account**: billing owner; can create/manage subaccounts; consolidated reporting.
- **Subaccount**: isolated resources (numbers, messaging services, apps) and usage; can be suspended/closed independently.

Operational model:
- Use subaccounts to isolate environments (prod/stage), tenants, or business units.
- Centralize billing and compliance at the parent where possible.

### Account lifecycle states

Twilio accounts have a `status` field:
- `active`: normal operation
- `suspended`: traffic blocked; resources retained
- `closed`: account closed; resources may be released; irreversible in practice

### Usage records vs billing

- **Usage Records API**: near-real-time usage events (minutes, messages, etc.) with categories.
- **Invoices**: monthly billing artifacts; not always suitable for alerting.
- For anomaly detection, prefer Usage Records with daily/hourly granularity.

### Phone number inventory

Twilio numbers are resources with:
- E.164 phone number
- capabilities: `sms`, `mms`, `voice`, `fax`
- configuration: Voice URL, Messaging webhook, status callback, emergency address (US), etc.

At scale:
- Use **Messaging Services** with **number pools** and **geo-matching** for cost/throughput optimization.
- Avoid binding application logic directly to a single number.

### Compliance surfaces (high-level)

- **A2P 10DLC (US)**: Brand + Campaign registration; required for many US A2P SMS use cases.
- **Toll-Free verification (US/CA)**: required for higher deliverability and throughput.
- **SHAKEN/STIR (Voice)**: caller ID attestation; impacts call completion and labeling.
- **TrustHub**: customer profiles, end-user profiles, supporting documents, bundles.

### Webhooks and auditability

- Messaging/Voice status callbacks are critical for delivery and debugging.
- Twilio Console provides audit events; programmatic access varies by product. Where APIs are limited, capture your own audit trail (who/what/when) in your automation.

---

## Installation & Setup

### Official Python SDK — Admin / Account Management

**Repository:** https://github.com/twilio/twilio-python  
**PyPI:** `pip install twilio` · **Supported:** Python 3.7–3.13

```python
from twilio.rest import Client
client = Client()

# List subaccounts
for acct in client.api.v2010.accounts.list():
    print(acct.sid, acct.friendly_name, acct.status)

# Create subaccount
sub = client.api.v2010.accounts.create(friendly_name="Staging Account")
sub_client = Client(client.username, client.password, sub.sid)

# Rotate auth token (master account key management)
keys = client.api.v2010.accounts(client.account_sid).keys.list()
for k in keys:
    print(k.sid, k.friendly_name, k.date_created)
```

Source: [twilio/twilio-python — accounts](https://github.com/twilio/twilio-python/blob/main/twilio/rest/api/v2010/account/__init__.py)

### Ubuntu 22.04/24.04

```bash
sudo apt-get update
sudo apt-get install -y curl jq python3.11 python3.11-venv python3-pip ca-certificates gnupg
```

Install Node.js 20.11.1 (NodeSource):

```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version   # expect v20.x
npm --version
```

Install Twilio CLI 5.6.0:

```bash
sudo npm install -g [email protected]
twilio --version
```

Optional: install Twilio CLI plugins commonly used in admin workflows:

```bash
twilio plugins:install @twilio-labs/[email protected]
twilio plugins:install @twilio-labs/[email protected]
twilio plugins:install @twilio-labs/[email protected]
```

Python environment:

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip==24.0
pip install twilio==9.4.1 requests==2.31.0 python-dateutil==2.9.0.post0
```

### Fedora 39/40

```bash
sudo dnf install -y curl jq python3.11 python3.11-pip python3.11-virtualenv ca-certificates
sudo dnf install -y nodejs npm
node --version
```

Install Twilio CLI:

```bash
sudo npm install -g [email protected]
twilio --version
```

Python venv:

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip==24.0
pip install twilio==9.4.1 requests==2.31.0 python-dateutil==2.9.0.post0
```

### macOS 14 (Intel + Apple Silicon)

Install Homebrew (if needed), then:

```bash
brew update
brew install jq [email protected] node@20
```

Ensure Node 20 is active:

```bash
brew link --overwrite node@20
node --version
```

Install Twilio CLI:

```bash
npm install -g [email protected]
twilio --version
```

Python venv:

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip==24.0
pip install twilio==9.4.1 requests==2.31.0 python-dateutil==2.9.0.post0
```

### Twilio CLI authentication

Twilio CLI stores profiles under:

- macOS/Linux: `~/.twilio-cli/config.json`

Login interactively (writes profile):

```bash
twilio login
```

Non-interactive (CI) via env vars:

```bash
export TWILIO_ACCOUNT_SID="ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
export TWILIO_AUTH_TOKEN="your_auth_token"
```

Verify:

```bash
twilio api:core:accounts:fetch --sid "$TWILIO_ACCOUNT_SID"
```

---

## Key Capabilities

### Subaccount lifecycle management

Operations:
- Create subaccount with deterministic naming and metadata.
- Rotate credentials (where supported) and distribute secrets.
- Suspend subaccount during incident response.
- Close subaccount after resource cleanup.

Key production guardrails:
- Never close a subaccount until:
  - all phone numbers are released/ported
  - messaging services are drained
  - webhooks are disabled or pointed to a safe sink
  - Verify services and SendGrid integrations are detached (if used)

### Usage monitoring and anomaly detection

- Pull daily usage by category (SMS, MMS, Voice minutes, Verify, etc.).
- Aggregate across subaccounts.