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

# Autenticación

> Cómo autenticar peticiones usando API keys

# Autenticación

Cada petición a la Business API debe incluir una API key válida en el header `X-API-Key`.

## Obtener una API Key

Las API keys se gestionan desde el **Dashboard de YaVendio** — no existe un endpoint programático para la gestión de keys.

<Steps>
  <Step title="Navegar a configuración de APIs">
    Inicia sesión en el [Dashboard de YaVendio](https://ya.onl) y ve a **Configuración → Claves API**.
  </Step>

  <Step title="Crear una nueva key">
    Haz clic en **"Crear API Key"**. Asigna un nombre descriptivo (ej. "Integración ERP").
  </Step>

  <Step title="Copiar tu key">
    La key completa se muestra **solo una vez** al momento de crearla. Cópiala y guárdala de forma segura. Después el dashboard solo conserva su prefijo (`yv_live_v1_Xk3Rt9pQz...`) para identificarla.
  </Step>
</Steps>

## Formato de la Key

Una key tiene la forma `yv_live_v1_` seguida de 43 caracteres aleatorios:

```
yv_live_v1_Xk3Rt9pQzL7mN2vB8cD4fG6hJ1kM5nP0rS9tU3wY7xZ
```

<Note>
  El dashboard crea siempre keys de tipo `live`. **No existe un ambiente sandbox**: una key
  de prueba operaría sobre los mismos datos productivos, así que no hay una versión "segura"
  de la credencial con la que experimentar.
</Note>

## Usar la API Key

Incluye la key en cada petición mediante el header `X-API-Key`:

```bash theme={null}
curl -H "X-API-Key: yv_live_v1_tu_api_key" \
  https://api.ya.onl/v1/orders
```

## Alcances (Scopes)

Hoy **todas las API keys tienen acceso completo** a todos los endpoints: el dashboard crea las keys sin alcances asignados y todavía no ofrece dónde elegirlos.

El modelo de alcances sí está implementado en la API. Cada endpoint declara el suyo — `orders:read`, `products:read`, `products:write`, `conversations:read`, `contacts:read`, `company:read`, `webhooks:read`, `webhooks:write`, `outbound:send`, `outbound:read` — y la página de referencia de cada uno indica cuál le corresponde. Si una key tuviera alcances asignados y le faltara el que el endpoint requiere, la petición recibiría `403 Forbidden`:

```json 403 Forbidden theme={null}
{
  "type": "ForbiddenError",
  "detail": "Missing required scope: orders:read"
}
```

<Note>
  Mientras no puedas elegir alcances, trata cada key como una credencial de acceso total: crea una por integración y elimínala cuando dejes de usarla.
</Note>

## Estados de la Key

Las keys visibles en el dashboard tienen dos estados posibles:

| Estado | Significado |
| - | - |
| **Activa** | La key es válida y acepta peticiones |
| **Revocada** | La key fue desactivada y todas las peticiones son rechazadas con 401 |

## Información en el Dashboard

La tabla de API keys en el dashboard muestra:

* **Nombre** — el nombre que asignaste al crear la key
* **Alcance** — hoy muestra siempre "Órdenes y Productos", porque todas las keys se crean con acceso completo
* **Estado** — Activa o Revocada
* **Secret Key** — solo el prefijo (`yv_live_v1_Xk3Rt9pQz...`)
* **Creada** — cuándo se creó la key
* **Último uso** — fecha de la última petición realizada con la key

Para eliminar una key, haz clic en el ícono de papelera junto a ella. Esta acción es **irreversible** — cualquier integración que use la key comenzará a recibir errores 401 inmediatamente.

## Respuestas de Error

| Status | Cuándo |
| - | - |
| `401 Unauthorized` | API key faltante, inválida, expirada o revocada |
| `403 Forbidden` | La key es válida pero no tiene el alcance que el endpoint requiere. Como hoy las keys se crean sin alcances, en la práctica no deberías verlo |

```json 401 Unauthorized theme={null}
{
  "type": "UnauthorizedError",
  "detail": "Invalid or missing API key"
}
```

## Buenas Prácticas

<Warning>
  Nunca expongas tu API key en código del lado del cliente (JavaScript en el navegador, apps móviles). Siempre llama a la API desde tu backend.
</Warning>

* **Usa variables de entorno** para almacenar API keys — nunca las escribas directamente en el código fuente.
* **Crea keys separadas** para cada integración o ambiente (desarrollo, staging, producción).
* **Rota las keys periódicamente** — elimina la key anterior y crea una nueva desde el dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.