Skip to content

Authentication

The Smoothdev CLI supports multiple authentication methods: Auth0 JWT for interactive use and API keys for CI/CD workflows.

Auth0 Authentication

The CLI uses Auth0's device flow for secure, browser-based authentication.

How It Works

  1. Run smooth auth login
  2. A device code and verification URL are displayed
  3. Your browser opens automatically (or visit the URL manually)
  4. Enter the device code when prompted
  5. Authorize the Smoothdev application
  6. The CLI automatically continues once authenticated

Login

smooth auth login

Example Output:

Authenticating with Auth0...

Please visit: https://auth.production.smoothdev.io/activate
Enter code: ABCD-EFGH

Waiting for authorization...
Authentication successful! You can now use the CLI.

Token Storage

JWT tokens are securely stored at:

  • Location: ~/.smoothdevio/token.json
  • Permissions: 0600 (read/write for owner only)
  • Contents: JWT token and expiration timestamp

The token is automatically refreshed when it expires.

Logout

Remove stored authentication credentials:

smooth auth logout

This deletes the token file from your system.

API Key Authentication

API keys provide non-interactive authentication, ideal for CI/CD pipelines and automated workflows.

Set API Key

smooth auth apikey-set your_api_key_here

Show Current API Key

smooth auth apikey-show

Clear API Key

smooth auth apikey-clear

Authentication Modes

Switch between authentication methods:

# Show current mode
smooth auth mode-show

# Set to API key mode (for CI/CD)
smooth auth mode-set api-key

# Set to JWT mode (interactive)
smooth auth mode-set jwt

# Auto-detect (default)
smooth auth mode-set auto

Get an API Key

To obtain an API key:

  1. Log in to your Smoothdev Dashboard
  2. Navigate to API Access in the sidebar
  3. Click New Personal Key
  4. Enter a name for your key and click Create
  5. Copy the key immediately (it's only shown once)

For detailed webapp instructions, see the Web Dashboard Guide.

For pricing and usage limits, see smoothdev.io/pricing.

GitHub Authentication

For commands that interact with GitHub (e.g., --push flag), you need a GitHub personal access token.

Create GitHub Token

  1. Go to GitHub Settings → Developer settings → Personal access tokens
  2. Click "Generate new token (classic)"
  3. Give it a descriptive name (e.g., "Smoothdev CLI")
  4. Select scopes:
  5. repo (full control of private repositories)
  6. read:org (read organization data)
  7. Click "Generate token"
  8. Copy the token immediately

Configure GitHub Token

Option 1: Environment Variable (Recommended for CI/CD)

export GITHUB_TOKEN=ghp_your_token_here

Option 2: User Config (Recommended for Local Development)

smooth config set github_token ghp_your_token_here

The token is stored in ~/.smoothdevio/config.json with secure permissions (0600).

Option 3: Alternative Environment Variable

export GH_TOKEN=ghp_your_token_here

Security Best Practices

Token Security

  1. Never commit tokens - Keep tokens in user config or environment variables
  2. Use secure permissions - Config files are created with 0600 permissions
  3. Rotate regularly - Update tokens periodically
  4. Limit scope - Only grant necessary permissions

File Permissions

Verify secure permissions on config files:

ls -la ~/.smoothdevio/

Expected Output:

drwx------  3 user group  96 Nov 15 10:00 .
-rw-------  1 user group 256 Nov 15 10:00 config.json
-rw-------  1 user group 512 Nov 15 10:00 token.json

Token Storage Locations

Token Type Location Permissions Committed?
JWT Token ~/.smoothdevio/token.json 0600 No
GitHub Token ~/.smoothdevio/config.json or env 0600 No

Troubleshooting

"Authentication required" Error

Problem: No valid authentication found.

Solution:

# Login with Auth0
smooth auth login

"Token expired" Error

Problem: JWT token has expired.

Solution:

The token should auto-refresh. If it doesn't:

# Re-authenticate
smooth auth logout
smooth auth login

"GitHub token not found" Error

Problem: GitHub token not configured for --push commands.

Solution:

# Set GitHub token
smooth config set github_token ghp_your_token_here

# Or use environment variable
export GITHUB_TOKEN=ghp_your_token_here

"Permission denied" on Config Files

Problem: Can't read/write config files.

Solution:

# Fix permissions
chmod 700 ~/.smoothdevio
chmod 600 ~/.smoothdevio/*.json

CI/CD Integration

Use API key authentication for automated CI/CD workflows.

GitHub Actions

name: PR Summary
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  generate-summary:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

      - uses: smoothdev-io/pr-summary-action@v1
        with:
          api_key: ${{ secrets.SMOOTHDEV_API_KEY }}
          push_to_pr: true

Manual CLI in CI/CD

- name: Generate PR Summary
  env:
    SMOOTHDEV_API_KEY: ${{ secrets.SMOOTHDEV_API_KEY }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    pip install smooth-cli
    smooth pr generate --pr-number ${{ github.event.pull_request.number }} --push

Environment Variables

Variable Description
SMOOTHDEV_API_KEY Your Smoothdev API key
GITHUB_TOKEN GitHub token for PR/release operations

Security and Data Handling

Smoothdev encrypts customer data in transit and at rest using tenant-scoped encryption keys. Source data is processed only for the requested operation and is not retained long term. Generated artifacts are returned to the user. Operational metrics and validation logs are retained to improve system reliability and quality.

Limitations

  • JWT tokens expire after 24 hours; the CLI automatically refreshes tokens when possible
  • API keys do not expire but can be revoked from the web dashboard
  • Maximum of 10 API keys per user
  • API keys are tenant-scoped and cannot access other tenants' data
  • Auth0 device flow requires browser access; headless environments must use API keys
  • Token files are stored with 0600 permissions; environments without filesystem access must use environment variables

See Also