> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Authentication

> Authenticate the Telnyx CLI by setting the TELNYX_API_KEY environment variable so commands can call Telnyx APIs on your account's behalf.

The Telnyx CLI authenticates using an API key set via environment variable.

## Setting Your API Key

Set the `TELNYX_API_KEY` environment variable:

```bash theme={null}
export TELNYX_API_KEY=KEY_xxxxxxxxxxxxx
```

<Tip>
  Add this line to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) to persist it across terminal sessions.
</Tip>

## Verify Authentication

Test that your credentials are working by running any command:

```bash theme={null}
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](https://portal.telnyx.com/)
2. Navigate to [API Keys](https://portal.telnyx.com/#/app/api-keys)
3. Click **Create API Key**
4. Copy the key (it won't be shown again)

<Note>
  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.
</Note>

## 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:

```bash theme={null}
# 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:

```bash theme={null}
telnyx-prod phone-numbers list
telnyx-staging phone-numbers list
```

### Option 2: Separate Terminal Sessions

Set different API keys in different terminal windows:

```bash theme={null}
# 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:

```bash theme={null}
TELNYX_API_KEY=KEY_other_xxx telnyx balance retrieve
```

## CI/CD Integration

### GitHub Actions

```yaml theme={null}
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

```yaml theme={null}
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

```bash theme={null}
#!/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

<AccordionGroup>
  <Accordion title="Never commit API keys to version control">
    Use environment variables or secrets management. Add `.env` files to `.gitignore`.
  </Accordion>

  <Accordion title="Use separate keys for environments">
    Create different API keys for production, staging, and development. This limits blast radius if a key is compromised.
  </Accordion>

  <Accordion title="Rotate keys periodically">
    Regenerate API keys periodically and update your configurations.
  </Accordion>

  <Accordion title="Use secrets managers in CI/CD">
    Store API keys in GitHub Secrets, GitLab CI Variables, AWS Secrets Manager, HashiCorp Vault, etc.
  </Accordion>
</AccordionGroup>

## 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](https://portal.telnyx.com/#/app/api-keys)
* 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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/development/cli/getting-started/quickstart">
    Run your first CLI commands
  </Card>

  <Card title="General Usage" icon="book-open" href="/development/cli/general-usage">
    Output formats, scripting, and CI/CD
  </Card>
</CardGroup>

***