docs: comprehensive atmn CLI documentation

mintlify/api-reference/cli/authentication.mdx

@@ -0,0 +1,217 @@
+---
+title: "Authentication"
+description: "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:
+
+```bash
+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
+
+<Note>
+The OAuth flow uses PKCE (Proof Key for Code Exchange) for enhanced security.
+</Note>
+
+## API Key Management
+
+### Key Types and Prefixes
+
+The CLI generates two API keys with distinct prefixes:
+
+<ParamField body="AUTUMN_SECRET_KEY" type="string">
+  **Sandbox key** with prefix `am_sk_test_*` — for development and testing
+</ParamField>
+
+<ParamField body="AUTUMN_PROD_SECRET_KEY" type="string">
+  **Production key** with prefix `am_sk_live_*` — for production environment
+</ParamField>
+
+### Environment File Structure
+
+Keys are automatically saved to a `.env` file in your current directory:
+
+<CodeGroup>
+
+```bash .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=...
+```
+
+</CodeGroup>
+
+### 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:
+
+<ParamField body="-p, --prod" type="flag">
+  Use production environment instead of sandbox
+</ParamField>
+
+<ParamField body="-l, --local" type="flag">
+  Use localhost:8080 API server instead of api.useautumn.com
+</ParamField>
+
+### Flag Combinations
+
+<CodeGroup>
+
+```bash Default (Sandbox + Remote API)
+atmn push
+# Uses: AUTUMN_SECRET_KEY → api.useautumn.com
+```
+
+```bash Production + Remote API
+atmn push --prod
+# Uses: AUTUMN_PROD_SECRET_KEY → api.useautumn.com
+```
+
+```bash Local Development Server
+atmn push --local
+# Uses: AUTUMN_SECRET_KEY → localhost:8080
+```
+
+```bash Production + Local API
+atmn push --local --prod
+# Uses: AUTUMN_PROD_SECRET_KEY → localhost:8080
+```
+
+</CodeGroup>
+
+### Environment URLs
+
+<ParamField body="Production API" type="string">
+  `https://api.useautumn.com`
+</ParamField>
+
+<ParamField body="Production Dashboard" type="string">
+  `https://app.useautumn.com`
+</ParamField>
+
+<ParamField body="Local API" type="string">
+  `http://localhost:8080`
+</ParamField>
+
+<ParamField body="Local Dashboard" type="string">
+  `http://localhost:3000`
+</ParamField>
+
+## Authentication Commands
+
+### Check Environment
+
+Display your current authentication status and organization info:
+
+```bash
+atmn env
+```
+
+Example output:
+
+```
+Organization: Acme Corp
+Slug: acme-corp
+Environment: Sandbox
+```
+
+### Logout
+
+Remove stored API keys from your `.env` file:
+
+```bash
+atmn logout
+```
+
+This removes both `AUTUMN_SECRET_KEY` and `AUTUMN_PROD_SECRET_KEY` from your environment file.
+
+<Warning>
+After logout, you'll need to run `atmn login` again to use CLI commands.
+</Warning>
+
+## 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
+
+<Note>
+**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
+</Note>
+
+### CI/CD Setup
+
+For automated deployments, set environment variables directly:
+
+```bash
+# GitHub Actions, etc.
+export AUTUMN_SECRET_KEY="am_sk_test_..."
+export AUTUMN_PROD_SECRET_KEY="am_sk_live_..."
+```
+
+See the [CI/CD guide](/api-reference/cli/ci-cd) for complete setup instructions.