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

# Autenticación

> Cómo autenticarse con el API de Zynvo

## Flujo de Autenticación

El API de Zynvo utiliza un sistema de autenticación de dos pasos:

1. **API Key**: Identifica tu cuenta de desarrollador
2. **JWT Token**: Proporciona acceso temporal a los recursos

### Obtener tus API Keys

Zynvo proporciona **dos API Keys separadas** para cada desarrollador:

* **Sandbox API Key**: Para desarrollo y pruebas
* **Production API Key**: Para operaciones en producción

<Warning>
  Las API Keys son específicas del ambiente. No puedes usar una API Key de sandbox en producción ni viceversa.
</Warning>

#### Cómo obtenerlas:

1. Inicia sesión en el [Dashboard de Zynvo](https://app.zynvo.com)
2. Navega a **Configuración** → **API Keys**
3. Verás dos secciones:
   * **Sandbox API Key**: Para pruebas
   * **Production API Key**: Para producción
4. Copia cada key de forma segura (solo se muestra una vez)

<Note>
  Mantén tus API Keys seguras y nunca las compartas públicamente. Trata tus keys como contraseñas.
</Note>

## Paso 1: Obtener un JWT Token

Antes de usar cualquier endpoint, debes obtener un JWT token temporal usando tu API Key:

<CodeGroup>
  ```bash Sandbox theme={null}
  curl -X POST https://api.zynvo.uy/v1/tokens \
    -H "X-API-Key: tu_sandbox_api_key" \
    -H "X-Sandbox-Mode: true"
  ```

  ```bash Production theme={null}
  curl -X POST https://api.zynvo.uy/v1/tokens \
    -H "X-API-Key: tu_production_api_key" \
    -H "X-Sandbox-Mode: false"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.zynvo.uy/v1/tokens', {
    method: 'POST',
    headers: {
      'X-API-Key': 'tu_sandbox_api_key',
      'X-Sandbox-Mode': 'true'
    }
  });

  const { data } = await response.json();
  const accessToken = data.access_token;
  ```

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

  response = requests.post(
      'https://api.zynvo.uy/v1/tokens',
      headers={
          'X-API-Key': 'tu_sandbox_api_key',
          'X-Sandbox-Mode': 'true'
      }
  )

  data = response.json()['data']
  access_token = data['access_token']
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}
```

El token expira en 1 hora (3600 segundos) por defecto.

## Paso 2: Usar el Token en Requests

Incluye el token JWT y la API Key en cada solicitud:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.zynvo.uy/v1/enterprises/210000000018 \
    -H "X-API-Key: tu_sandbox_api_key" \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
    -H "X-Sandbox-Mode: true"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.zynvo.uy/v1/enterprises/210000000018',
    {
      headers: {
        'X-API-Key': 'tu_sandbox_api_key',
        'Authorization': `Bearer ${accessToken}`,
        'X-Sandbox-Mode': 'true'
      }
    }
  );
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api.zynvo.uy/v1/enterprises/210000000018',
      headers={
          'X-API-Key': 'tu_sandbox_api_key',
          'Authorization': f'Bearer {access_token}',
          'X-Sandbox-Mode': 'true'
      }
  )
  ```
</CodeGroup>

### Headers Requeridos

| Header           | Descripción                                            |
| ---------------- | ------------------------------------------------------ |
| `X-API-Key`      | Tu API Key (sandbox o production)                      |
| `Authorization`  | JWT token en formato `Bearer {token}`                  |
| `X-Sandbox-Mode` | `true` para sandbox, `false` o ausente para production |

<Warning>
  El ambiente del header `X-Sandbox-Mode` DEBE coincidir con el ambiente de tu API Key. Si usas una API Key de sandbox, debes enviar `X-Sandbox-Mode: true`.
</Warning>

## Errores de Autenticación

### 401 Unauthorized

Si el token no es válido o está ausente:

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Token de autenticación inválido o ausente"
  }
}
```

### 403 Forbidden

Si el token es válido pero no tiene permisos para acceder al recurso:

```json theme={null}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "No tienes permisos para acceder a este recurso"
  }
}
```

## Mejores Prácticas

<AccordionGroup>
  <Accordion title="Rota tus tokens regularmente">
    Por seguridad, genera nuevos tokens periódicamente y elimina los antiguos desde el dashboard.
  </Accordion>

  <Accordion title="Usa variables de entorno">
    Almacena tu token en variables de entorno, nunca en el código fuente.

    ```bash theme={null}
    export ZYNVO_API_TOKEN="tu_token_de_api"
    ```
  </Accordion>

  <Accordion title="Tokens por ambiente">
    Usa diferentes tokens para desarrollo, staging y producción.
  </Accordion>

  <Accordion title="Monitorea el uso">
    Revisa regularmente los logs de uso de tu token en el dashboard para detectar actividad inusual.
  </Accordion>
</AccordionGroup>