On this page

Subaccounts

The Twilio CLI also features support for issuing commands tied to subaccounts. Subaccounts are commonly created to separate usage by team, product, customer, and more.

Instructions on how to create a Twilio subaccount can be found in this Twilio Support guide, and there is more general information about subaccounts in the Twilio IAM docs.

API commands

For all non-twilio api:core commands, please create a profile (twilio login or twilio profiles:create) using the subaccount SID and an API Key SID and Secret.

Some examples of "non-core" commands are:

twilio phone-numbers:list
twilio email:set
twilio api:serverless:v1:services:list

Below are the two methods for issuing commands tied to a subaccount.

Set a subaccount as the active profile

To make all subsequent CLI commands via the intended subaccount:

Set the subaccount's profile as active
twilio profiles:use SUBACCOUNT_PROFILE_ID
Issue commands as usual. Commands will use the active subaccount's credentials
twilio phone-numbers:list

Specify the subaccount profile

You can apply the subaccount to individual commands by using the -p or --profile flag:

twilio phone-numbers:list -p SUBACCOUNT_PROFILE_ID

Refer to the profiles documentation for more information about profiles and profile management.

Core API commands

Core API commands are any CLI command that reference resources under the V2010 API (twilio api:core:.*), such as twilio api:core:messages:create.

Profiles created for parent accounts cannot be used to manage subaccounts, as the twilio login process creates a Standard API Key. An appropriate Main API Key is necessary to work with subaccounts, and can be created here.

You must use environment variables if you want access to subaccounts for this family of commands. There are two options: use a Main API Key, or the Parent Account SID and Auth Token.

Once you have your subaccount SID, you can add the --account-sid parameter to a command to reference a specific subaccount, provided it's a twilio api:core command.

For example:

1$ export TWILIO_ACCOUNT_SID=ACXXXXXXXX
2$ export TWILIO_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXX
3$ export TWILIO_API_SECRET=XXXXXXXXXXXXXXXXXXXXXXXXXXXX
4$ twilio api:core:available-phone-numbers:local:list \
5    --area-code="415" \
6    --country-code US \
7    --account-sid=SUBACCOUNT_SID

(error)

Danger

In the rare case that you cannot create an API Key or do not have access to one, you can leverage the Account SID and Auth Token of the subaccount's parent account as environment variables for authorization.

The Account SID and Auth Token can be retrieved from the console.

1$ export TWILIO_ACCOUNT_SID=ACXXXXXXXX
2$ export TWILIO_AUTH_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXX
3$ twilio api:core:available-phone-numbers:local:list \
4    --area-code="415" \
5    --country-code US \
6    --account-sid=SUBACCOUNT_SID

Using this method is highly discouraged as it increases the risk of exposing your Auth Token.