Налаштування REST API

Кожен продукт NimbusNexus — це REST API: JSON через HTTPS з вашим API-ключем у заголовку Authorization. Ця сторінка проведе вас від відсутності ключа до першого успішного виклику. Виберіть мову вгорі сторінки, і приклади перемкнуться на неї. REST означає curl; для TypeScript, Python і Go використовується звичайний HTTP-клієнт кожної мови, SDK не потрібен.

1 · Отримайте API-ключ

Застосунки: Webhooks, Inboxes, QR-коди та Request Bins. Відкрийте API keys у консолі акаунта і створіть ключ для продукту, який хочете викликати. Кожен ключ належить одному продукту. Там само виберіть його область дії: admin, read, а для Webhooks ще й publish. Скопіюйте ключ, щойно він зʼявиться, бо він показується лише один раз. Ключ застосунку — це JWT, тому він починається з eyJ.

Інфраструктура: VM, сховище, бази даних і мережа. Створіть ключ у дашборді в розділі Settings → API keys. Він привʼязаний до одного проєкту. Області дії та ротацію описано на сторінці Автентифікація.

Не тримайте ключ у вихідному коді. Експортуйте його в оболонці або зберігайте у сховищі секретів:

Shell

export WEBHOOKS_API_KEY="<your-api-key>"

2 · Надсилайте його в кожному запиті

Надсилайте ключ як bearer-токен. API застосунків також приймають його як X-API-Key: <key>.

HTTP

Authorization: Bearer <your-api-key>

Кожен продукт має власний базовий URL:

Продукт	Базовий URL
Webhooks	`https://webhooks.nimbusnexus.net/v1`
Inboxes	`https://inboxes.nimbusnexus.net/v1`
QR-коди	`https://qr.nimbusnexus.net/v1`
Request Bins	`https://bins.nimbusnexus.net/v1`
Інфраструктура	`https://api.nimbusnexus.net`

3 · Перший виклик

GET /v1/auth/me у Webhooks повертає дані про надісланий ключ: його область дії та робочий простір, якому він належить. Більше нічого він не читає, тому викликати його може будь-який дійсний ключ.

curl https://webhooks.nimbusnexus.net/v1/auth/me \
  -H "Authorization: Bearer $WEBHOOKS_API_KEY"

У відповіді вказано ваш робочий простір:

JSON

{
  "scope": "admin",
  "workspace_id": "<workspace-id>"
}

Інші поля вказують, який це тип облікових даних. Для API-ключа email і created_at дорівнюють null.

4 · Розбирайте помилки

На невдалий запит API відповідає статусом 4xx або 5xx і форматом помилки, єдиним для всіх продуктів:

JSON

{
  "error": {
    "code": "unauthorized",
    "message": "…",
    "details": { "reason": "missing" },
    "request_id": "…"
  }
}

Розгалужуйте обробку за code, а не за статусом чи повідомленням. unauthorized означає, що ключ не надійшов або його відкликано. invalid_credential означає, що ключ недійсний: випустіть новий, бо повтор не допоможе. forbidden означає, що ключ дійсний, але не може виконати цю дію: бракує області дії чи ролі або продукт не ввімкнено для вашого робочого простору. Усі коди перелічено на сторінках Автентифікація і Помилки. Звертаючись у підтримку, вказуйте request_id.

Що далі

Довідник API: усі операції всіх продуктів із викликом вашою мовою.
SDK і CLI: ті самі виклики, але повтори, перевірку підписів і пагінацію вони беруть на себе.
Швидкий старт для продуктів: Webhooks, Inboxes, Request Bins, ваша перша VM.