Authentication

OAuth login, API key management, and environment configuration

The atmn CLI uses OAuth 2.0 for secure authentication and automatically manages API keys for both sandbox and production environments.

OAuth Login Flow

Authenticate with your Autumn account using the login command:

atmn login

Interactive Mode

When running in an interactive terminal, the CLI provides a beautiful login experience:

1. Local Callback Server: Starts a temporary server on ports 31448-31452
2. Browser Integration: Opens your default browser to Autumn’s Auth0 login page
3. Organization Selection: Choose which organization to authenticate with
4. Automatic Key Generation: Creates sandbox and production API keys
5. Environment Setup: Saves keys to your .env file

Headless Mode

For CI/CD environments or when no TTY is available:

1. The CLI opens your browser with the OAuth URL
2. Provides a fallback URL you can copy/paste manually
3. Waits for the OAuth callback with a timeout

The OAuth flow uses PKCE (Proof Key for Code Exchange) for enhanced security.

API Key Management

Key Types and Prefixes

The CLI generates two API keys with distinct prefixes:

AUTUMN_SECRET_KEY · string

Sandbox key with prefix am_sk_test_* — for development and testing

AUTUMN_PROD_SECRET_KEY · string

Production key with prefix am_sk_live_* — for production environment

Environment File Structure

Keys are automatically saved to a .env file in your current directory:

.env

# Autumn API Keys (generated by atmn login)
AUTUMN_SECRET_KEY=am_sk_test_1234567890abcdef1234567890abcdef
AUTUMN_PROD_SECRET_KEY=am_sk_live_abcdef1234567890abcdef1234567890

# Your other environment variables
DATABASE_URL=...
STRIPE_SECRET_KEY=...

Key Resolution

The CLI looks for environment files in this order:

1. Current directory .env
2. Parent directories (walks up the directory tree)
3. Root directory .env

Environment Selection

Control which environment and API server the CLI uses with global flags:

-p, --prod · flag

Use production environment instead of sandbox

-l, --local · flag

Use localhost:8080 API server instead of api.useautumn.com

Flag Combinations

Default (Sandbox + Remote API)

atmn push
# Uses: AUTUMN_SECRET_KEY → api.useautumn.com

Environment URLs

Production API · string

https://api.useautumn.com

Production Dashboard · string

https://app.useautumn.com

Local API · string

http://localhost:8080

Local Dashboard · string

http://localhost:3000

Authentication Commands

Check Environment

Display your current authentication status and organization info:

atmn env

Example output:

Organization: Acme Corp
Slug: acme-corp
Environment: Sandbox

Logout

Remove stored API keys from your .env file:

atmn logout

This removes both AUTUMN_SECRET_KEY and AUTUMN_PROD_SECRET_KEY from your environment file.

After logout, you’ll need to run atmn login again to use CLI commands.

Error Handling

Automatic Re-authentication

The CLI automatically handles expired or invalid tokens:

1. 401 Unauthorized responses trigger the OAuth flow
2. New tokens are generated and stored
3. The original request is retried
4. You’re notified of the re-authentication

Common Issues

No API key found:

Error: No API key found. Run `atmn login` to authenticate.

Solution: Run atmn login to generate API keys

Invalid API key:

Error: 401 Unauthorized - Invalid API key

Solution: The CLI will automatically prompt for re-authentication

Wrong environment:

Error: API key is for sandbox but --prod flag was used

Solution: Remove the --prod flag or login again to generate production keys

Security Best Practices

Keep your API keys secure:

• Add .env to your .gitignore file
• Never commit API keys to version control
• Use different keys for development and production
• Rotate keys regularly through the Autumn dashboard

CI/CD Setup

For automated deployments, set environment variables directly:

# GitHub Actions, etc.
export AUTUMN_SECRET_KEY="am_sk_test_..."
export AUTUMN_PROD_SECRET_KEY="am_sk_live_..."

See the CI/CD guide for complete setup instructions.