Skip to main content
The Telnyx CLI supports multiple authentication methods and named profiles for managing different accounts or environments.

​
Why Multiple Auth Methods?

Different environments call for different authentication approaches:
MethodBest ForTrade-offs
Config fileLocal developmentPersistent, convenient; tied to your machine
Environment variableCI/CD, containers, scriptsPortable, no file needed; must be set each session
Command-line flagQuick one-off commandsImmediate; exposes key in shell history
The CLI checks these in order: flag → environment variable → config file. This lets you override your default config for specific scenarios without changing it.

​
Authentication Methods

The easiest way to configure authentication: 
telnyx auth setup
You’ll be prompted to enter your API key. The configuration is stored securely in ~/.config/telnyx/config.json.

​
2. Environment Variable

Set your API key as an environment variable: 
export TELNYX_API_KEY=KEY_xxxxxxxxxxxxx
This takes precedence over the config file, making it useful for:
  • CI/CD pipelines
  • Containerized environments
  • Temporary overrides

​
3. Command-Line Flag

Pass the API key directly (not recommended for scripts): 
telnyx number list --api-key KEY_xxxxxxxxxxxxx

​
Verify Authentication

Check your current authentication status: 
telnyx auth status
Example output: 
✓ Authenticated

Account:     My Company
Email:       [email protected]
Balance:     $125.50
Profile:     default

​
Multiple Profiles

Use named profiles to manage multiple Telnyx accounts or environments (production, staging, development).

​
When to Use Profiles

Profiles solve common multi-environment challenges:
  • Separate accounts — If your company has distinct Telnyx accounts for different business units or clients
  • Environment isolation — Keep production and staging API keys separate to prevent accidents
  • Team workflows — Share profile names (not keys) so scripts work across team members’ machines
Combine profiles with environment variables in CI/CD: use --profile locally for convenience, and TELNYX_API_KEY in pipelines where you pull secrets from a vault.

​
Create a Profile

telnyx auth setup --profile production
telnyx auth setup --profile staging

​
List Profiles

telnyx profile list

​
Use a Profile

Specify the profile for any command: 
telnyx number list --profile production
telnyx billing balance --profile staging

​
Set Default Profile

telnyx profile set-default production

​
Delete a Profile

telnyx profile delete staging

​
Configuration File

The CLI stores configuration in ~/.config/telnyx/config.json: 
{
  "defaultProfile": "production",
  "profiles": {
    "default": {
      "apiKey": "KEY_xxxxxxxxxxxxx"
    },
    "production": {
      "apiKey": "KEY_yyyyyyyyyyyyy"
    },
    "staging": {
      "apiKey": "KEY_zzzzzzzzzzzzz"
    }
  }
}
Keep your config file secure. It contains sensitive API keys. The file is created with restricted permissions (600) by default.

​
Environment Variables

VariableDescription
TELNYX_API_KEYAPI key (overrides config file)
TELNYX_PROFILEDefault profile name
TELNYX_CONFIG_DIRCustom config directory

​
Example: CI/CD Usage

# GitHub Actions
env:
  TELNYX_API_KEY: ${{ secrets.TELNYX_API_KEY }}

steps:
  - run: telnyx message send --from +15551234567 --to +15559876543 --text "Build complete"

# Shell script
export TELNYX_API_KEY="$PROD_API_KEY"
telnyx number list

​
Getting Your API Key

  1. Log in to the Telnyx Portal
  2. Navigate to API Keys
  3. Click Create API Key
  4. Copy the key (it won’t be shown again)
API keys start with KEY_. If you’re using a v1 API key (starting with a different prefix), you’ll need to create a new v2 key.

​
Security Best Practices

Never commit API keys to version control. Use secrets management in your CI/CD platform.
Create different API keys for production, staging, and development. This limits blast radius if a key is compromised.
Regenerate API keys periodically and update your configurations.
The config file should only be readable by your user:
chmod 600 ~/.config/telnyx/config.json

​
Troubleshooting

​
”Unauthorized” Error

Error: Request failed with status 401: Unauthorized
Solutions:
  • Verify your API key is correct: telnyx auth status
  • Check if the key has been revoked in the Portal
  • Ensure TELNYX_API_KEY isn’t set to an old value

​
Config File Not Found

Error: No configuration found
Solutions:
  • Run telnyx auth setup to create the config
  • Check if ~/.config/telnyx/config.json exists
  • Verify file permissions

​
Wrong Profile Being Used

Solutions:
  • Explicitly specify: --profile myprofile
  • Check default: telnyx profile list
  • Unset environment variable: unset TELNYX_PROFILE

​
Next Steps

Quickstart

Run your first CLI commands

General Usage

Output formats, scripting, and CI/CD