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: 
export TELNYX_API_KEY=KEY_xxxxxxxxxxxxx
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: 
telnyx balance retrieve
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: 
# Add to ~/.bashrc or ~/.zshrc
alias telnyx-prod='TELNYX_API_KEY=KEY_production_xxx telnyx'
alias telnyx-staging='TELNYX_API_KEY=KEY_staging_xxx telnyx'
Usage: 
telnyx-prod phone-numbers list
telnyx-staging phone-numbers list

​
Option 2: Separate Terminal Sessions

Set different API keys in different terminal windows: 
# Terminal 1 (Production)
export TELNYX_API_KEY=KEY_production_xxx

# Terminal 2 (Staging)
export TELNYX_API_KEY=KEY_staging_xxx

​
Option 3: Inline Override

Override the API key for a single command: 
TELNYX_API_KEY=KEY_other_xxx telnyx balance retrieve

​
CI/CD Integration

​
GitHub Actions

name: Deploy Notification

on:
  deployment:
    types: [completed]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Install Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'

      - name: Install Telnyx CLI
        run: go install github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest

      - name: Send SMS notification
        env:
          TELNYX_API_KEY: ${{ secrets.TELNYX_API_KEY }}
        run: |
          telnyx messages send \
            --from "${{ vars.TELNYX_NUMBER }}" \
            --to "${{ vars.ONCALL_NUMBER }}" \
            --text "✅ Deployment complete: ${{ github.repository }}"

​
GitLab CI

notify:
  image: golang:1.22
  script:
    - go install github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest
    - export PATH="$PATH:$(go env GOPATH)/bin"
    - telnyx messages send --from $FROM_NUMBER --to $TO_NUMBER --text "Build complete"
  variables:
    TELNYX_API_KEY: $TELNYX_API_KEY

​
Shell Scripts

#!/bin/bash
# deploy-notify.sh

# Load from environment or secrets manager
export TELNYX_API_KEY="${TELNYX_API_KEY:-$(vault read -field=api_key secret/telnyx)}"

telnyx messages send \
  --from "+15551234567" \
  --to "+15559876543" \
  --text "Deployment complete at $(date)"

​
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

Error: Request failed with status 401: Unauthorized
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