Autenticación

Cada solicitud a /v1 lleva una clave de API en la cabecera Authorization. La clave identifica su cuenta y el entorno (sandbox o live) y contiene la lista de operaciones que puede realizar.

Authorization: Bearer <your API key>

Claves de API

Una clave tiene la forma ak_live_ o ak_sandbox_ seguida de 22 caracteres. El prefijo selecciona el entorno: una clave sandbox nunca toca datos live ni la facturación, y una clave live nunca se ejecuta en sandbox; vea Sandbox y live. Una solicitud cuya clave no tenga esta forma se rechaza antes de cualquier otro proceso.

• Leeri emite las claves bajo petición. Escriba a hello@leeri.ai e indique qué scopes necesita. Todavía no hay una pantalla de emisión de claves por autoservicio.
• Una clave es un secreto de servidor. Guárdela en su almacén de secretos o en el entorno, nunca en el control de versiones, una aplicación móvil o una página web. Solo almacenamos su hash, por lo que una clave perdida no puede mostrarse de nuevo: solicite una nueva.
• La rotación se solapa. Para rotar, emitimos una clave nueva y damos a la antigua una fecha de caducidad; ambas se autentican hasta que la antigua caduca, y a partir de entonces responde 401. Migre sus servicios a la clave nueva dentro de esa ventana.
• Revoque ante la duda. Si una clave pudo filtrarse, avísenos y la desactivaremos. La revocación y los cambios de scope de una clave llegan a la API en aproximadamente un minuto.

Scopes

Cada clave lleva una lista explícita de scopes. Una ruta exige uno de ellos, y una clave sin scopes no es admitida en ninguna parte: todas las rutas responden 403. Solicite solo los scopes que usa la integración.

Scope	Permite
checks:write	Crear verificaciones y lotes (POST /v1/checks, POST /v1/checks/batch) y enviar informes de direcciones (POST /v1/address-reports).
checks:read	Leer una verificación o un lote por id (GET /v1/checks/{check_id}, GET /v1/checks/batch/{batch_id}) y reproducir un veredicto (POST /v1/verdicts/{verdict_id}/rederive).
webhooks:manage	Crear, listar, rotar y desactivar endpoints de webhook.
telegram:manage	Emitir códigos de vinculación de Telegram de un solo uso y listar o revocar los chats vinculados a su cuenta.

Un reparto habitual es una clave con checks:write y checks:read para el servicio que verifica, y otra clave con webhooks:manage para las herramientas de despliegue que registran endpoints.

Realizar una solicitud autenticada

La llamada siguiente usa una clave sandbox y la dirección de prueba de sandbox, que siempre responde pending; vea Sandbox y live. La clave se lee del entorno y nunca se escribe en el código.

curl

curl -s -X POST https://api.leeri.ai/v1/checks \
  -H "Authorization: Bearer $LEERI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"address","asset":"BTC","address":"1PENDNGCHECKADDRESSFRSANDBXTEST99"}'

Node.js

const response = await fetch('https://api.leeri.ai/v1/checks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LEERI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ subject: 'address', asset: 'BTC', address: '1PENDNGCHECKADDRESSFRSANDBXTEST99' }),
});

if (response.status === 401) throw new Error('API key missing, malformed, unknown or expired');
if (response.status === 403) throw new Error('API key lacks the checks:write scope');
console.log((await response.json()).data.status);

Python

import os
import requests

response = requests.post(
    "https://api.leeri.ai/v1/checks",
    headers={"Authorization": f"Bearer {os.environ['LEERI_API_KEY']}"},
    json={"subject": "address", "asset": "BTC", "address": "1PENDNGCHECKADDRESSFRSANDBXTEST99"},
    timeout=30,
)

if response.status_code == 401:
    raise RuntimeError("API key missing, malformed, unknown or expired")
if response.status_code == 403:
    raise RuntimeError("API key lacks the checks:write scope")
print(response.json()["data"]["status"])

401 y 403

Estado	Código	Significado	Qué hacer
401	AUTH_ERROR	La cabecera falta o está mal formada, o la clave es desconocida, ha sido revocada o ha caducado.	Revise la cabecera y la clave. No repita la misma solicitud.
403	SCOPE_ERROR	La clave es válida pero no lleva el scope que exige la ruta.	Solicite el scope que falta o use la clave que lo tiene.

La autenticación fallida está limitada por dirección IP de origen: tras cinco intentos fallidos en un minuto, las solicitudes posteriores desde esa dirección responden 429 RATE_LIMIT_EXCEEDED hasta que termina el minuto. Un bucle de reintentos que siga enviando una clave incorrecta bloquea, por tanto, su propio servidor, así que deténgase ante un 401. Vea Límites de solicitudes y cuotas.

Un id que pertenece a otra cuenta, o al otro entorno, responde 404 exactamente igual que un id que no existe, de modo que una clave nunca sirve para averiguar si existe un recurso ajeno.

Llame desde su backend

La API está pensada para uso entre servidores. No admite solicitudes de origen cruzado desde sitios web de terceros, por lo que un navegador no puede llamarla, y poner una clave en un cliente web o móvil la expondría. Envíe las verificaciones desde su backend y entregue a su front end solo el resultado que quiera mostrar.