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

# Autenticación

> Cómo autenticarte con la API de La Pyme usando API keys o OAuth delegado

## Overview

La API de La Pyme acepta dos credenciales en el header `Authorization: Bearer ...`:

1. **API keys** para integraciones técnicas o de servidor.
2. **Access tokens OAuth delegados** para clientes públicos como CLIs o agentes que actúan en nombre de una persona usuaria.

Ambos modelos siguen usando scopes de API y ambos quedan ligados a una organización concreta antes de ejecutar capacidades en `apps/api`.

## Cuándo usar cada uno

* Usá **API keys** si controlás el backend o podés guardar secretos de forma segura.
* Usá **OAuth delegado** si el cliente corre del lado de la persona usuaria, por ejemplo una CLI o un agente local, y querés evitar copiar/pegar credenciales largas desde el dashboard.

## Obtener tu API Key

### Paso 1: Acceder al Dashboard

1. Iniciá sesión en [Dashboard de La Pyme](https://app.lapyme.com.ar)
2. Navegá a **Configuración** > **Integraciones**
3. En la sección "API Keys", hacé click en **Crear nuevo API Key**

### Paso 2: Configurar Permisos

Seleccioná los permisos que necesitás para tu integración:

| Scope              | Descripción                                             |
| ------------------ | ------------------------------------------------------- |
| `customers:read`   | Leer información de clientes                            |
| `customers:write`  | Crear, actualizar y eliminar clientes (incluye read)    |
| `products:read`    | Leer información de productos                           |
| `products:write`   | Crear, actualizar y eliminar productos (incluye read)   |
| `warehouses:read`  | Leer ubicaciones y depósitos                            |
| `warehouses:write` | Crear y actualizar ubicaciones (incluye read)           |
| `purchases:read`   | Leer compras y órdenes de compra                        |
| `purchases:write`  | Crear compras y operar órdenes de compra (incluye read) |
| `sales:read`       | Leer ventas                                             |
| `sales:write`      | Crear ventas (incluye read)                             |
| `orders:read`      | Leer pedidos y remitos                                  |
| `orders:write`     | Crear y operar pedidos (incluye read)                   |
| `payments:read`    | Leer cobranzas y pagos a proveedores                    |
| `payments:write`   | Registrar y anular cobranzas y pagos (incluye read)     |
| `inventory:read`   | Leer inventario y movimientos                           |
| `inventory:write`  | Crear movimientos de inventario (incluye read)          |
| `settings:read`    | Leer organización y referencias fiscales seguras        |
| `accounting:read`  | Leer contabilidad                                       |
| `price_lists:read` | Leer listas de precios y su configuración               |
| `reports:read`     | Ejecutar consultas analíticas                           |
| `webhooks:read`    | Descubrir eventos y leer endpoints de webhook           |
| `webhooks:write`   | Crear y administrar endpoints de webhook (incluye read) |
| `admin`            | Acceso completo a todos los recursos                    |

<Warning>
  Los API keys con scope `admin` tienen acceso completo a tu organización. Usá este scope solo cuando sea necesario y mantené estas keys seguras.
</Warning>

<Info>
  Algunas credenciales existentes conservan compatibilidad por operación con
  scopes anteriores. Para integraciones nuevas, usá siempre el scope canónico que
  figura como `x-required-scopes` en OpenAPI.
</Info>

### Paso 3: Generar y Guardar

1. Hacé click en **Generar API Key**
2. **Copiá y guardá el API key inmediatamente** - no lo vas a poder ver de nuevo
3. Dale un nombre descriptivo para identificarlo fácilmente

## Usar tu API Key

Incluí tu API key en el header `Authorization` con el prefijo `Bearer`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.lapyme.com.ar/api/v1/warehouses?limit=1" \
    -H "Authorization: Bearer tu_api_key_aqui" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.lapyme.com.ar/api/v1/warehouses?limit=1', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer tu_api_key_aqui',
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  ```

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

  headers = {
      'Authorization': 'Bearer tu_api_key_aqui',
      'Content-Type': 'application/json'
  }

  response = requests.get('https://api.lapyme.com.ar/api/v1/warehouses', params={'limit': 1}, headers=headers)
  data = response.json()
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.lapyme.com.ar/api/v1/warehouses?limit=1",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer tu_api_key_aqui",
      "Content-Type: application/json"
    ]
  ]);

  $response = curl_exec($curl);
  $data = json_decode($response, true);

  curl_close($curl);
  ?>
  ```
</CodeGroup>

## Usar OAuth delegado desde la CLI

La CLI pública de La Pyme está pensada para instalarse globalmente y arrancar sin configuración manual extra.

Flujo esperado:

1. La CLI inicia Authorization Code + PKCE.
2. Se abre el navegador para login y consentimiento.
3. Elegís la organización y aprobás el acceso.
4. La CLI recibe el callback local, intercambia el código por tokens y guarda el refresh token localmente.
5. Los próximos requests de la CLI usan `Authorization: Bearer <access_token>`.

Ejemplo mínimo:

```bash theme={null}
pnpm i -g lapyme
lapyme login
```

Después del login:

```bash theme={null}
lapyme smoke --path /api/v1/warehouses?limit=1
```

<Info>
  La CLI no guarda refresh tokens en La Pyme. La persistencia local de tokens es responsabilidad del cliente público.
</Info>

<Info>
  `lapyme login` usa el cliente OAuth público de producción, `https://app.lapyme.com.ar`, `https://api.lapyme.com.ar` y un callback local en `http://127.0.0.1:8787/callback`. Los flags y variables de entorno siguen disponibles para desarrollo o pruebas.
</Info>

## Validar tu credencial

Podés verificar que la credencial funciona correctamente haciendo un request a cualquier endpoint. Si el bearer token es válido, vas a recibir una response exitosa. Si hay algún problema, vas a recibir uno de estos errores:

### Credencial faltante

```json theme={null}
{
  "request_id": "req_auth_1",
  "error": {
    "type": "authentication_error",
    "code": "AUTHENTICATION_REQUIRED",
    "message": "API key is required in the Authorization header",
    "retryable": false,
    "details": []
  }
}
```

### Credencial inválida

```json theme={null}
{
  "request_id": "req_auth_2",
  "error": {
    "type": "authentication_error",
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required.",
    "retryable": false,
    "details": []
  }
}
```

### Permisos Insuficientes

```json theme={null}
{
  "request_id": "req_auth_3",
  "error": {
    "type": "authorization_error",
    "code": "FORBIDDEN",
    "message": "Your API key does not have permission for this operation",
    "retryable": false,
    "details": []
  }
}
```

## Mejores Prácticas de Seguridad

### Monitoreo

Monitoreá el uso de tus API keys y aplicaciones conectadas desde el Dashboard:

* **Última actividad**: Cuándo se usó cada key por última vez
* **Requests por día**: Cantidad de requests realizadas
* **Errores**: Requests fallidas por key

<Info>
  Si detectás actividad sospechosa o pensás que una credencial fue comprometida, revocá el API key o la aplicación conectada inmediatamente desde el Dashboard.
</Info>

## Rate Limiting

La cuota se aplica por **organización**, no por credencial individual:

* **Cuota principal**: 5000 requests por hora por organización
* **Burst protection**: 120 requests por minuto por organización
* **Qué comparte cuota**: todas las API keys y todos los access tokens OAuth delegados de la misma organización
* **Dónde aplica**: sobre la API pública autenticada (`/api/v1/*`)
* **Dónde no aplica**: `/health`, `OPTIONS`, rutas internas y webhooks
* **Headers**: cuando recibís `429`, la response incluye `Retry-After`, `X-RateLimit-*` y `RateLimit-*`

En la práctica, si tenés varias integraciones o agentes usando la API para la misma organización, todas consumen del mismo presupuesto.

### Qué hacer si recibís `429 RATE_LIMITED`

1. Leé el header `Retry-After`.
2. Esperá esa cantidad de segundos.
3. Reintentá la misma operación después de la ventana de espera.

Si tu integración necesita manejar retries automáticos, tomá `Retry-After` como la fuente de verdad para el backoff.

Si necesitás un límite mayor, contactanos en [hola@lapyme.com.ar](mailto:hola@lapyme.com.ar).

## Próximos Pasos

Una vez que tenés tu método de autenticación configurado:

1. Probá hacer tu primer request a un endpoint de lectura.
2. Explorá la referencia completa en la sección **Docs API**.
3. Revisá [Endpoints y recursos](/api-reference/v1) si vas a integrar el módulo de compras.