Skip to content

Authentication

The SmoothDev CLI uses Auth0 JWT for secure authentication. API key authentication is coming soon 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.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 (Coming Soon)

API keys will provide non-interactive authentication, ideal for CI/CD pipelines. This feature is currently in development.

Planned Features:

  • Non-interactive authentication for automated workflows
  • Secure API key storage and management
  • Commands: smooth auth apikey-set, apikey-show, apikey-clear
  • Multiple authentication mode support (auto, jwt, api-key)

For now, use Auth0 JWT authentication for all workflows. For CI/CD integration, see the CI/CD Integration section below.

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

For now, CI/CD workflows require Auth0 authentication. API key support for non-interactive authentication is coming soon.

GitHub Actions (Current Approach)

- name: Authenticate with SmoothDev
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    # Note: Requires manual Auth0 login setup
    # API key support coming soon for automated workflows
    smooth pr generate --pr-number ${{ github.event.pull_request.number }}

Future: API Key Support

Once API key authentication is available, CI/CD integration will be simplified:

# Coming soon
- name: Authenticate with SmoothDev
  env:
    SMOOTHDEV_API_KEY: ${{ secrets.SMOOTHDEV_API_KEY }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    smooth auth mode-set api-key
    smooth pr generate --pr-number ${{ github.event.pull_request.number }}

See Also