Autenticación

Cómo autenticarte en la API pública de Plur-e con una clave de API del tenant — la cabecera bearer, los cuatro mensajes 401, el plazo de revocación y los límites de tasa que responden 429.

Respuesta rápida

Envía tu clave de API del tenant en cada petición como Authorization: Bearer plrapi_…. Una clave desconocida, revocada, caducada o cuyo tenant está inactivo responde 401 con el código invalid_api_key y un mensaje que indica el caso. Una clave revocada deja de funcionar en un minuto. Cada clave puede enviar 120 peticiones por minuto; la siguiente responde 429 sin cuerpo.

La cabecera bearer

curl -s "https://api.plur-e.com/api/public/v1/bc/methods" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

La clave empieza por plrapi_ seguido de 43 caracteres (50 en total).
Viaja solo en la cabecera Authorization. No la pongas en la URL ni en el cuerpo.
Solo la API pública la acepta. La clave no autentica en ningún otro punto de Plur-e, y un token de usuario de Plur-e no autentica en la API pública.
El tenant se toma de la clave. Ningún valor de cabecera, ruta o cuerpo puede elegir otro tenant.

401 cuando se rechaza la clave

Una clave rechazada responde 401 Unauthorized con la cabecera WWW-Authenticate: Bearer realm="plure-public-api" y un cuerpo problem+json cuyo code es invalid_api_key. El detail es uno de cuatro mensajes fijos:

Mensaje	Qué significa	Qué hacer
`The Plur-e API key is not valid.`	Falta la cabecera, no es una clave de Plur-e, o la clave no existe	Revisa la cabecera y copia la clave de nuevo; si la perdiste, crea una nueva
`The Plur-e API key was revoked.`	Un administrador revocó la clave	Crea una clave nueva
`The Plur-e API key expired on 2026-12-31. Create a new one in Developers > APIs > API keys.`	La clave superó su fecha de caducidad (el mensaje muestra la fecha)	Crea una clave nueva y rótala en tu integración
`The tenant of this Plur-e API key is not active.`	El tenant dueño de la clave está bloqueado	Contacta con tu administrador de Plur-e o con soporte

Los mensajes de detail van siempre en inglés.

{
  "type": "https://plur-e.com/docs/developers/errors#invalid_api_key",
  "title": "invalid_api_key",
  "status": 401,
  "detail": "The Plur-e API key was revoked.",
  "code": "invalid_api_key",
  "errorCode": null,
  "traceId": "0HN7…"
}

Revocación

Revocar una clave en Developers → APIs → API keys es definitivo. Plur-e guarda en memoria el resultado de la comprobación de una clave hasta 60 segundos, así que las integraciones que sigan usando la clave funcionan como máximo un minuto después de revocarla; luego cada llamada responde 401 con el mensaje "was revoked". La ventana funciona también al revés: una clave probada antes de existir puede seguir respondiendo "not valid" hasta un minuto después de crearla.

Rota antes de revocar

Crea primero la clave de reemplazo, despliégala, comprueba en el Usage log que la clave antigua ya no se usa y solo entonces revócala.

Límites de tasa

Hay dos límites. Ambos usan una ventana fija de un minuto.

Límite	Valor	Cuando se supera
Por clave de API	120 peticiones por minuto	`429 Too Many Requests` sin cuerpo
Por dirección IP del cliente	600 peticiones por minuto en toda la API pública, contadas antes de comprobar la clave	`429` con cuerpo problem+json (`code` = `rate_limited`) y cabecera `Retry-After` en segundos

Ante un 429, espera a que empiece el siguiente minuto (o los segundos de Retry-After, si viene) y reintenta con una espera corta creciente. El 429 por clave no lleva Retry-After, así que reparte tus llamadas en lugar de enviarlas en ráfagas. Las peticiones rechazadas por el límite de IP no se escriben en el Usage log.

Licencia y scopes

Una vez aceptada la clave, cada operación comprueba dos cosas más:

Licencia. Si el tenant no tiene una suscripción Developer APIs activa, la llamada responde 403 con el error plure_1320.
Scope. Cada operación exige un scope. Una clave sin él responde 403 con el error plure_1321 y un mensaje que nombra el scope que falta. Consulta Claves de API para ver la lista.