Autenticación y llaves
Cada llamada lleva una llave en el encabezado Authorization:
Authorization: Bearer sk_live_ab12cd34_…
Tipos de llave
| Llave | Dónde vive | Para qué sirve |
|---|---|---|
sk_test_… / sk_live_… (secreta) |
Solo en tu backend | Todos los endpoints, según sus permisos |
pk_test_… / pk_live_… (publicable) |
En tu página web | Solo POST /v1/device, y solo desde los orígenes registrados |
Prueba y producción están separados. Una llave test nunca ve ni modifica datos live: uso, casos, reglas, listas, configuración, webhooks y llaves son independientes. Una llave secreta en /v1/device, o una publicable en cualquier otro endpoint, regresa 401.
Permisos (scopes)
| Scope | Permite |
|---|---|
score |
POST /v1/score, POST /v1/labels |
screen |
POST /v1/screen, y screen=true en /v1/score |
lists:read / lists:write |
Leer / modificar listas |
rules:read / rules:write |
Leer / modificar reglas |
admin |
Llaves, ajustes, uso, webhooks, borrado de datos |
Las llaves nuevas tienen score + screen por defecto. Da a cada sistema solo lo que necesita: tu servicio de pagos no necesita admin.
Crear, rotar y revocar llaves
Con una llave admin:
POST /v1/keys{"name": "backend", "kind": "secret", "scopes": ["score"]}regresa la llave en texto claro una sola vez.POST /v1/keys/{id}/rotate{"grace_hours": 24}crea la nueva llave; la anterior sigue funcionando durante el periodo de gracia (0–168 h) y después regresa 401.DELETE /v1/keys/{id}revoca de inmediato.
Una llave solo administra llaves de su mismo entorno.
Límites de uso
| Límite | Por defecto |
|---|---|
| Por llave secreta | 50 solicitudes/s (ráfagas de 100) |
| Por cuenta y entorno | 200 solicitudes/s (ráfagas de 400) |
/v1/device por llave publicable |
100/s (ráfagas de 200) |
/v1/device por IP del navegador |
1/s (ráfagas de 20) |
Al superarlo recibes 429 con el encabezado Retry-After (segundos). Si necesitas más, escríbenos.
Errores
Los errores regresan JSON con un campo detail en español e inglés:
{"detail": "La llave no tiene el permiso 'screen' / Key lacks the 'screen' scope"}
| Código | Significa |
|---|---|
| 401 | Llave ausente, inválida, expirada o del tipo equivocado |
| 403 | La llave no tiene el permiso, o el origen no está registrado (/v1/device) |
| 404 | No existe (o pertenece a otro entorno) |
| 409 | Conflicto de estado (p. ej. rotar una llave que ya no está activa) |
| 422 | El cuerpo no es válido; aquí detail es una lista con un elemento por campo (loc, msg, type) |
| 429 | Límite de uso superado; reintenta después de Retry-After |
| 503 | Screening pedido con /v1/screen pero las listas no están disponibles |
Las llamadas rechazadas (401, 403, 422, 429, 503) no se cobran.