Автентифікація

Кожен запит /v1 містить один ключ API в заголовку Authorization. Ключ ідентифікує ваш обліковий запис і середовище (sandbox або live) та містить список операцій, які йому дозволено виконувати.

Authorization: Bearer <your API key>

Ключі API

Ключ виглядає як ak_live_ або ak_sandbox_ і 22 символи після нього. Префікс визначає середовище: ключ sandbox ніколи не торкається live-даних чи тарифікації, а live-ключ ніколи не працює в sandbox; див. Sandbox і live. Запит із ключем, що не відповідає цій формі, відхиляється ще до будь-якої іншої обробки.

• Ключі видає Leeri за запитом. Напишіть на hello@leeri.ai і вкажіть, які scope вам потрібні. Екрана самостійного випуску ключів поки немає.
• Ключ — це серверний секрет. Зберігайте його в сховищі секретів або в змінних середовища, ніколи не в системі контролю версій, мобільному застосунку чи вебсторінці. Ми зберігаємо лише його хеш, тому втрачений ключ показати знову неможливо: попросіть новий.
• Ротація з перекриттям. Для ротації ми видаємо новий ключ і задаємо старому дату завершення; обидва автентифікуються, доки старий не спливе, після чого він відповідає 401. Перенесіть сервіси на новий ключ у цьому вікні.
• Відкликайте за підозри. Якщо ключ міг витекти, повідомте нас, і ми його вимкнемо. Відкликання та зміни scope ключа діють в API приблизно за хвилину.

Scope

Кожен ключ має явний список scope. Маршрут вимагає один із них, а ключ без scope не допускається нікуди: кожен маршрут відповідає 403. Просіть лише ті scope, які використовує інтеграція.

Scope	Дозволяє
checks:write	Створювати перевірки та пакети (POST /v1/checks, POST /v1/checks/batch) і надсилати звіти про адреси (POST /v1/address-reports).
checks:read	Читати перевірку чи пакет за ідентифікатором (GET /v1/checks/{check_id}, GET /v1/checks/batch/{batch_id}) і відтворювати вердикт (POST /v1/verdicts/{verdict_id}/rederive).
webhooks:manage	Створювати, переглядати, ротувати й вимикати кінцеві точки вебхуків.
telegram:manage	Видавати одноразові коди прив'язки Telegram, переглядати й відкликати чати, прив'язані до вашого облікового запису.

Типовий поділ: ключ із checks:write і checks:read для сервісу, що виконує перевірки, та окремий ключ із webhooks:manage для інструментів розгортання, які реєструють кінцеві точки.

Автентифікований запит

Запит нижче використовує ключ sandbox і тестову адресу sandbox, яка завжди відповідає pending; див. Sandbox і live. Ключ береться зі змінної середовища і ніколи не пишеться в коді.

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 і 403

Статус	Код	Значення	Що робити
401	AUTH_ERROR	Заголовок відсутній або має хибну форму, або ключ невідомий, відкликаний чи прострочений.	Перевірте заголовок і ключ. Не повторюйте той самий запит.
403	SCOPE_ERROR	Ключ дійсний, але не має scope, потрібного маршруту.	Попросіть відсутній scope або скористайтеся ключем, який його має.

Невдала автентифікація обмежується за IP-адресою джерела: після п'яти невдалих спроб за хвилину подальші запити з цієї адреси відповідають 429 RATE_LIMIT_EXCEEDED до кінця хвилини. Тому цикл повторів, що далі надсилає хибний ключ, блокує ваш власний сервер: зупиняйтеся на 401. Див. Обмеження частоти запитів і ліміти.

Ідентифікатор, що належить іншому обліковому запису або іншому середовищу, відповідає 404 точно як ідентифікатор, що не існує, тож за допомогою ключа неможливо дізнатися, чи існує чужий ресурс.

Викликайте зі свого бекенду

API призначене для взаємодії сервер-сервер. Воно не дозволяє міждоменних запитів зі сторонніх сайтів, тому браузер не може його викликати, а ключ у вебклієнті чи мобільному клієнті був би розкритий. Надсилайте перевірки зі свого бекенду, а фронтенду віддавайте лише той результат, який хочете показати.