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

# Authentication

> Learn how to authenticate with the ZenFlow API

# Authentication

The ZenFlow API uses API Keys to authenticate requests. You can manage your API keys from the ZenFlow dashboard.

## Getting an API Key

1. Log in to your [ZenFlow Dashboard](https://app.zenflow.com)
2. Navigate to **Settings** > **API Keys**
3. Click **Create API Key**
4. Configure your key:
   * **Name**: A descriptive name (e.g., "ERP Integration")
   * **Scopes**: Select the permissions your key needs
   * **Expiration**: Optional expiration date
5. Click **Create**
6. Copy your API key immediately - it won't be shown again

<Warning>
  Store your API key securely. Never commit it to version control or expose it
  in client-side code.
</Warning>

## Using Your API Key

Include your API key in the `X-API-Key` header with every request:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.zenflow.com.ar/api/v1/orders" \
    -H "X-API-Key: zenflow_live_abc123..."
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.zenflow.com.ar/api/v1/orders", {
    headers: {
      "X-API-Key": "zenflow_live_abc123...",
    },
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.zenflow.com.ar/api/v1/orders',
      headers={'X-API-Key': 'zenflow_live_abc123...'}
  )
  ```
</CodeGroup>

## API Key Format

ZenFlow API keys follow this format:

```
zenflow_live_<random_string>
zenflow_test_<random_string>
```

* `zenflow_live_*`: Production keys
* `zenflow_test_*`: Test/sandbox keys (coming soon)

## Scopes

API keys are scoped to specific permissions. Available scopes:

| Scope            | Description                  |
| ---------------- | ---------------------------- |
| `read:orders`    | Read order data              |
| `write:orders`   | Create and update orders     |
| `read:products`  | Read product catalog         |
| `write:products` | Create and update products   |
| `read:stock`     | Read inventory levels        |
| `write:stock`    | Update inventory             |
| `read:webhooks`  | View webhook configurations  |
| `write:webhooks` | Manage webhooks              |
| `admin`          | Full access to all resources |

### Scope Presets

For common use cases, we offer preset scope combinations:

| Preset      | Scopes                                                                      | Use Case                  |
| ----------- | --------------------------------------------------------------------------- | ------------------------- |
| Read Only   | `read:orders`, `read:products`, `read:stock`                                | Reporting and analytics   |
| ERP Sync    | `read:orders`, `write:orders`, `read:products`, `read:stock`, `write:stock` | Full ERP integration      |
| Stock Sync  | `read:products`, `read:stock`, `write:stock`                                | Inventory synchronization |
| Full Access | `admin`                                                                     | Administrative access     |

## Error Responses

### Invalid API Key

```json theme={null}
{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked"
  }
}
```

### Missing API Key

```json theme={null}
{
  "success": false,
  "error": {
    "code": "missing_api_key",
    "message": "API key is required. Include it in the X-API-Key header"
  }
}
```

### Insufficient Permissions

```json theme={null}
{
  "success": false,
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the required scope: write:orders"
  }
}
```

### Expired API Key

```json theme={null}
{
  "success": false,
  "error": {
    "code": "expired_api_key",
    "message": "This API key has expired"
  }
}
```

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Use Environment Variables" icon="key">
    Store API keys in environment variables, not in code
  </Card>

  <Card title="Minimum Permissions" icon="shield">
    Only request the scopes you actually need
  </Card>

  <Card title="Rotate Regularly" icon="rotate">
    Rotate your API keys periodically
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Review API key usage logs for suspicious activity
  </Card>
</CardGroup>

### Example: Environment Variables

```bash theme={null}
# .env file (never commit this!)
ZENFLOW_API_KEY=zenflow_live_abc123...
```

```javascript theme={null}
// Node.js
const apiKey = process.env.ZENFLOW_API_KEY;
```

```python theme={null}
# Python
import os
api_key = os.environ.get('ZENFLOW_API_KEY')
```

## Rotating API Keys

To rotate an API key:

1. Create a new API key with the same scopes
2. Update your application to use the new key
3. Verify the new key is working
4. Revoke the old key

<Note>
  You can have multiple active API keys. This allows for zero-downtime rotation.
</Note>

## IP Whitelisting (Optional)

For additional security, you can restrict API key usage to specific IP addresses:

1. Go to **Settings** > **API Keys**
2. Select your API key
3. Add allowed IP addresses or CIDR ranges
4. Save changes

```json theme={null}
{
  "ip_whitelist": ["192.168.1.100", "10.0.0.0/24"]
}
```

## Rate Limits

See [Rate Limits](/guides/rate-limits) for details on API rate limiting.