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

# Autenticación

> Autentica tus solicitudes con una API key, y crea, rota y revoca tus claves desde Configuración.

Cada solicitud a la API de clientes se autentica con una API key de tu empresa, enviada en el header `x-api-key`. Tú mismo creas, rotas y revocas tus claves desde Pruff, sin pedirle nada a nadie.

## Enviar la clave

Envía el valor completo de la clave, tal como lo viste al crearla, en el header `x-api-key` de cada solicitud:

```bash theme={null}
curl https://api.pruff.com/api/clients/invoices \
  -H "x-api-key: pruff_sk_<tu-clave>"
```

Las claves nuevas empiezan con `pruff_sk_` y siguen con 64 caracteres. Las claves que tu empresa ya usaba tienen otro formato y funcionan igual, con el mismo valor, sin que tengas que hacer nada.

Guarda la clave en tu servidor, por ejemplo en un gestor de secretos o en una variable de entorno. Nunca la expongas en un navegador ni en una aplicación móvil.

## Crear una clave

1. En Pruff, entra a **Configuración** → **Otros** → **Claves de API**.
2. Elige **Crear clave**.
3. Escribe un **Nombre** de 3 a 120 caracteres. Usa el nombre del sistema que la va a usar, por ejemplo `ERP producción`.
4. Elige la **Expiración**: 30 días, 90 días, 1 año o **Sin expiración**.
5. Confirma con **Crear clave** y copia la clave completa.

> [!WARNING]
>
> Pruff muestra la clave completa una sola vez. Después solo verás sus últimos cuatro caracteres, y no hay forma de recuperar el valor completo. Si lo pierdes, rota la clave.

Crea una clave por sistema. Así, si una se filtra, revocas solo esa y los demás sistemas siguen funcionando. Para administrar claves tu usuario necesita permiso para ello; si no ves la sección o los botones, pídele acceso a un administrador de tu empresa.

La lista muestra para cada clave su nombre, sus últimos cuatro caracteres, su estado, cuándo expira y cuándo se usó por última vez. Ese último dato se actualiza como máximo una vez cada 5 minutos.

| Estado | Significado |
| - | - |
| Activa | Funciona. |
| Expira pronto | Funciona, pero expira en 7 días o menos. |
| En rotación | Es la clave nueva de una rotación, y la anterior todavía funciona. |
| Revocada | Dejó de funcionar porque alguien la revocó. |
| Expirada | Dejó de funcionar porque llegó su fecha de expiración. |

## Expiración

Una clave con expiración deja de funcionar en el instante en que se cumple su plazo, contado desde su creación. Desde ese momento responde `401` y queda en la lista de claves inactivas. Una clave **Sin expiración** funciona hasta que la revoques.

Una clave expirada no se puede renovar. Crea una nueva o rota la clave antes de que expire: la clave nueva recibe una expiración nueva, del mismo plazo que la original, contado desde la rotación. Una clave sin expiración sigue sin expirar después de rotarla.

## Rotar una clave

Rota una clave para cambiar su valor sin cortar tu integración, o cuando sospeches que se filtró.

1. En **Claves de API**, elige **Rotar** en la fila de la clave.
2. Elige cuánto tiempo sigue funcionando la clave actual:
   * **Deja de funcionar ahora**: úsalo si la clave se filtró.
   * **24 horas**: para cambiarla sin corte.
   * **7 días**: si tu despliegue necesita más tiempo.
3. Confirma con **Rotar clave** y copia la clave nueva, que se muestra una sola vez.

La clave nueva conserva el nombre de la actual y recibe una expiración nueva, del mismo plazo que la original, contado desde la rotación. Si la actual no expira, la nueva tampoco. Durante el margen que elegiste, ambas claves funcionan: cambia tu sistema a la clave nueva y, al terminar el margen, la anterior responde `401`. La clave nueva aparece como **En rotación** hasta entonces, junto con la fecha en que la anterior deja de funcionar. La clave anterior sale de la lista en cuanto existe la nueva.

Para cortar la clave anterior antes de que termine su margen, revoca la clave nueva: eso termina ambos márgenes y las dos dejan de funcionar de inmediato. Si rotas una clave que todavía tiene una anterior en margen, ese margen termina de inmediato. Puedes rotar tanto claves nuevas como las que tu empresa ya tenía.

## Revocar una clave

Revoca una clave cuando un sistema deja de usarla o cuando se filtró y no necesitas un margen.

1. En **Claves de API**, elige **Revocar** en la fila de la clave.
2. Confirma con **Revocar clave**.

La revocación es inmediata y no se puede deshacer: toda solicitud con esa clave recibe `401` desde ese momento. La clave queda en la lista de claves inactivas, con la fecha y la persona que la revocó.

## Respuesta 401

Una clave que no se puede usar recibe siempre la misma respuesta, sin indicar el motivo:

```json theme={null}
{
  "message": "Unauthorized: Invalid API Key"
}
```

Recibes este `401` cuando:

* falta el header `x-api-key`;
* el valor no corresponde a ninguna clave;
* la clave fue revocada;
* la clave expiró;
* la clave fue rotada y terminó su margen;
* la cuenta de API de tu empresa no está habilitada.

Para saber cuál es tu caso, revisa el estado de la clave en **Configuración** → **Otros** → **Claves de API**. La clave anterior de una rotación ya no aparece en la lista, así que, si tu sistema sigue usándola, cambia a la clave nueva. Reintentar la misma solicitud no sirve: usa una clave activa.

## Límite de solicitudes

Todas las claves de tu empresa comparten un límite de 500 solicitudes por minuto. Las solicitudes rechazadas con `401` no cuentan, porque el límite se aplica después de autenticar. Algunos endpoints tienen además un límite propio, que aparece en su referencia.

Al superar el límite recibes `429`, con el header `Retry-After` y un body que indica cuánto esperar:

```json theme={null}
{
  "message": "Rate limit exceeded: 501 requests in the current 60s window, limit is 500. Retry in 12s.",
  "displayMessage": "Superaste el límite de 500 solicitudes cada 60 segundos. Vuelve a intentarlo en 12 segundos.",
  "data": {
    "code": "RATE_LIMIT_EXCEEDED",
    "scope": "All API keys of your company share this budget.",
    "limit": 500,
    "used": 501,
    "windowSeconds": 60,
    "retryAfterSeconds": 12,
    "resetAt": "2026-11-12T13:01:00.000Z",
    "hint": "Wait until resetAt (or honor the Retry-After header) before retrying. Avoid repeating identical requests: reuse responses you already fetched, use filters and larger pageSize values instead of one request per item, and cap your client concurrency."
  }
}
```

Espera hasta `resetAt`, o los segundos de `Retry-After`, antes de reintentar. Crear más claves no aumenta el límite, porque se comparte entre todas.


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