Skip to main content
The Telnyx CLI authenticates using an API key set via environment variable.

Setting Your API Key

Set the TELNYX_API_KEY environment variable:
Add this line to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist it across terminal sessions.

Verify Authentication

Test that your credentials are working by running any command:
If authenticated successfully, you’ll see your account balance. If not, you’ll receive an authentication error.

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.

Multiple Accounts

If you work with multiple Telnyx accounts (e.g., production and staging), you have several options:

Option 1: Shell Aliases

Create aliases for different accounts:
Usage:

Option 2: Separate Terminal Sessions

Set different API keys in different terminal windows:

Option 3: Inline Override

Override the API key for a single command:

CI/CD Integration

GitHub Actions

GitLab CI

Shell Scripts

Security Best Practices

Use environment variables or secrets management. Add .env files to .gitignore.
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.
Store API keys in GitHub Secrets, GitLab CI Variables, AWS Secrets Manager, HashiCorp Vault, etc.

Troubleshooting

”Unauthorized” Error

Solutions:
  • Verify your API key is set: echo $TELNYX_API_KEY
  • Check if the key starts with KEY_
  • Verify the key hasn’t been revoked in the Portal
  • Ensure there are no extra spaces or characters in the key

”No API key” Error

Solutions:
  • Set the environment variable: export TELNYX_API_KEY=KEY_xxx
  • Check for typos in the variable name
  • Ensure the variable is exported (not just set)

Next Steps

Quickstart

Run your first CLI commands

General Usage

Output formats, scripting, and CI/CD