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

# Authentication

> Authentication in Compozy is required to access cloud services, publish components to the registry, and manage your workflows in production. This guide covers how to authenticate with Compozy Cloud and manage your credentials securely.

## Quick Reference

Here's a quick overview of all available authentication commands:

| Command                          | Description                           |
| -------------------------------- | ------------------------------------- |
| `compozy login`                  | Log in to Compozy Cloud               |
| `compozy logout`                 | Log out and remove stored credentials |
| `compozy auth status`            | Check authentication status           |
| `compozy auth list`              | List all active sessions              |
| `compozy auth refresh`           | Manually refresh authentication token |
| `compozy auth revoke <token_id>` | Revoke a specific token               |
| `compozy auth revoke-all`        | Revoke all active tokens              |

## Authentication Methods

<CardGroup cols={2}>
  <Card title="CLI Login" icon="terminal">
    Authenticate using the Compozy CLI for local development and deployments.
  </Card>

  <Card title="API Keys" icon="key">
    Use API keys for programmatic access and CI/CD integrations.
  </Card>
</CardGroup>

## CLI Authentication

<Steps>
  <Step title="Login Command" icon="right-to-bracket">
    Use the following command to authenticate with Compozy Cloud:

    ```bash theme={"dark"}
    compozy login
    ```

    This will open your default browser to complete the authentication process.
  </Step>

  <Step title="Verify Authentication" icon="check">
    Confirm your authentication status:

    ```bash theme={"dark"}
    compozy auth status
    ```
  </Step>

  <Step title="Logout" icon="right-from-bracket">
    To logout and remove stored credentials:

    ```bash theme={"dark"}
    compozy logout
    ```
  </Step>
</Steps>

## API Keys

API keys provide secure, programmatic access to Compozy services. They are especially useful for CI/CD pipelines and automated deployments.

<Steps>
  <Step title="Generate API Key" icon="key">
    1. Visit the [Compozy Cloud Dashboard](https://app.compozy.dev)
    2. Navigate to Settings > API Keys
    3. Click "Generate New Key"
    4. Save the key securely - it won't be shown again
  </Step>

  <Step title="Configure API Key" icon="gear">
    Set your API key using one of these methods:

    <CodeGroup>
      ```bash Environment Variable theme={"dark"}
      export FLYZT_API_KEY=your_api_key_here
      ```

      ```yaml Configuration File theme={"dark"}
      # ~/.compozy/config.yaml
      auth:
        api_key: your_api_key_here
      ```
    </CodeGroup>
  </Step>

  <Step title="Key Management" icon="shield">
    Best practices for API key security:

    * Rotate keys regularly
    * Use different keys for different environments
    * Never commit keys to version control
    * Set appropriate key permissions and expiration
  </Step>
</Steps>

## CI/CD Integration

For secure authentication in CI/CD pipelines:

<CodeGroup>
  ```yaml GitHub Actions theme={"dark"}
  name: Deploy Compozy Workflow

  on:
    push:
      branches: [ main ]

  jobs:
    deploy:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v2
        - name: Deploy to Compozy Cloud
          env:
            FLYZT_API_KEY: ${{ secrets.FLYZT_API_KEY }}
          run: |
            compozy deploy
  ```

  ```yaml GitLab CI theme={"dark"}
  deploy:
    stage: deploy
    script:
      - compozy deploy
    environment:
      name: production
    variables:
      FLYZT_API_KEY: $CI_FLYZT_API_KEY
  ```
</CodeGroup>

## Token Management

<Steps>
  <Step title="View Active Sessions" icon="list">
    List all active authentication sessions:

    ```bash theme={"dark"}
    compozy auth list
    ```
  </Step>

  <Step title="Revoke Access" icon="trash">
    Revoke specific tokens or all active sessions:

    ```bash theme={"dark"}
    # Revoke specific token
    compozy auth revoke <token_id>

    # Revoke all tokens
    compozy auth revoke-all
    ```
  </Step>

  <Step title="Token Refresh" icon="rotate">
    Tokens are automatically refreshed when needed. Manual refresh:

    ```bash theme={"dark"}
    compozy auth refresh
    ```
  </Step>
</Steps>

## Security Best Practices

<Steps>
  <Step title="Credential Storage" icon="lock">
    * Use environment variables for API keys
    * Leverage secure credential managers
    * Never hardcode credentials in code
  </Step>

  <Step title="Access Control" icon="user-shield">
    * Follow the principle of least privilege
    * Regularly audit access permissions
    * Remove unused credentials promptly
  </Step>

  <Step title="Environment Separation" icon="layer-group">
    * Use different credentials per environment
    * Implement proper key rotation policies
    * Monitor credential usage patterns
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Invalid Credentials">
    * Verify your API key is correctly set
    * Check for environment variable conflicts
    * Ensure your token hasn't expired
    * Try logging out and back in
  </Accordion>

  <Accordion title="Authentication Failures">
    * Check your network connection
    * Verify your system time is accurate
    * Clear local credential cache
    * Contact support if issues persist
  </Accordion>

  <Accordion title="Token Expiration">
    * Tokens automatically refresh when needed
    * Manual refresh with `compozy auth refresh`
    * Generate new API key if expired
    * Check token expiration status
  </Accordion>
</AccordionGroup>

## Need Help?

* Run `compozy auth --help` for detailed command information
* Visit our [Discord community](https://discord.gg/compozy) for support
* Check our [troubleshooting guide](/cli/troubleshooting)
* Contact [Compozy Support](https://compozy.dev/support) for assistance