> ## 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.

# Autenticacion

> Aprende a autenticarte con la API de ZenFlow

# Autenticacion

La API de ZenFlow usa API Keys para autenticar las peticiones. Puedes administrar tus API keys desde el panel de ZenFlow.

## Obtener una API Key

1. Inicia sesion en tu [Panel de ZenFlow](https://app.zenflow.com)
2. Navega a **Configuracion** > **API Keys**
3. Haz clic en **Crear API Key**
4. Configura tu key:
   * **Nombre**: Un nombre descriptivo (ej: "Integracion ERP")
   * **Scopes**: Selecciona los permisos que tu key necesita
   * **Expiracion**: Fecha de expiracion opcional
5. Haz clic en **Crear**
6. Copia tu API key inmediatamente - no se mostrara de nuevo

<Warning>
  Guarda tu API key de forma segura. Nunca la guardes en control de versiones ni
  la expongas en codigo del lado del cliente.
</Warning>

## Usar tu API Key

Incluye tu API key en el header `X-API-Key` en cada peticion:

<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>

## Formato de API Key

Las API keys de ZenFlow siguen este formato:

```
zenflow_live_<cadena_aleatoria>
zenflow_test_<cadena_aleatoria>
```

* `zenflow_live_*`: Keys de produccion
* `zenflow_test_*`: Keys de prueba/sandbox (proximamente)

## Scopes (Permisos)

Las API keys tienen permisos especificos. Scopes disponibles:

| Scope            | Descripcion                          |
| ---------------- | ------------------------------------ |
| `read:orders`    | Leer datos de pedidos                |
| `write:orders`   | Crear y actualizar pedidos           |
| `read:products`  | Leer catalogo de productos           |
| `write:products` | Crear y actualizar productos         |
| `read:stock`     | Leer niveles de inventario           |
| `write:stock`    | Actualizar inventario                |
| `read:webhooks`  | Ver configuraciones de webhooks      |
| `write:webhooks` | Administrar webhooks                 |
| `admin`          | Acceso completo a todos los recursos |

### Presets de Scopes

Para casos de uso comunes, ofrecemos combinaciones predefinidas:

| Preset       | Scopes                                                                      | Caso de Uso                  |
| ------------ | --------------------------------------------------------------------------- | ---------------------------- |
| Solo Lectura | `read:orders`, `read:products`, `read:stock`                                | Reportes y analiticas        |
| Sync ERP     | `read:orders`, `write:orders`, `read:products`, `read:stock`, `write:stock` | Integracion ERP completa     |
| Sync Stock   | `read:products`, `read:stock`, `write:stock`                                | Sincronizacion de inventario |
| Acceso Total | `admin`                                                                     | Acceso administrativo        |

## Respuestas de Error

### API Key Invalida

```json theme={null}
{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "La API key proporcionada es invalida o ha sido revocada"
  }
}
```

### API Key Faltante

```json theme={null}
{
  "success": false,
  "error": {
    "code": "missing_api_key",
    "message": "Se requiere API key. Incluyela en el header X-API-Key"
  }
}
```

### Permisos Insuficientes

```json theme={null}
{
  "success": false,
  "error": {
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido: write:orders"
  }
}
```

### API Key Expirada

```json theme={null}
{
  "success": false,
  "error": {
    "code": "expired_api_key",
    "message": "Esta API key ha expirado"
  }
}
```

## Mejores Practicas de Seguridad

<CardGroup cols={2}>
  <Card title="Usa Variables de Entorno" icon="key">
    Guarda las API keys en variables de entorno, no en codigo
  </Card>

  <Card title="Permisos Minimos" icon="shield">
    Solo solicita los scopes que realmente necesitas
  </Card>

  <Card title="Rota Regularmente" icon="rotate">
    Rota tus API keys periodicamente
  </Card>

  <Card title="Monitorea Uso" icon="chart-line">
    Revisa los logs de uso de API keys para detectar actividad sospechosa
  </Card>
</CardGroup>

### Ejemplo: Variables de Entorno

```bash theme={null}
# archivo .env (nunca hagas commit de esto!)
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')
```

## Rotar API Keys

Para rotar una API key:

1. Crea una nueva API key con los mismos scopes
2. Actualiza tu aplicacion para usar la nueva key
3. Verifica que la nueva key funciona
4. Revoca la key antigua

<Note>
  Puedes tener multiples API keys activas. Esto permite rotacion sin tiempo de
  inactividad.
</Note>

## Lista Blanca de IPs (Opcional)

Para seguridad adicional, puedes restringir el uso de API keys a direcciones IP especificas:

1. Ve a **Configuracion** > **API Keys**
2. Selecciona tu API key
3. Agrega direcciones IP permitidas o rangos CIDR
4. Guarda los cambios

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

## Limites de Tasa

Consulta [Limites de Tasa](/es/guides/rate-limits) para detalles sobre rate limiting de la API.