Menu

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:

  1. Set the subaccount's profile as active

    twilio profiles:use SUBACCOUNT_PROFILE_ID
    
  2. 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:

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

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.

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

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

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

thanks-feedback-gif