Перейти до вмісту
NimbusNexus

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

API NimbusNexus на api.nimbusnexus.net приймає API-ключ у заголовку X-API-Key. Кожен ключ належить одній людині й працює в одному проєкті — з тими ролями й правилами доступу, з якими його створено.

Як виглядає запит

Надсилайте ключ у заголовку X-API-Key:

Shell
curl https://api.nimbusnexus.net/api/v1/instance/ \
  -H "X-API-Key: $NIMBUS_KEY"

Ключ — це значення api_key, яке ви отримуєте під час створення: ID ключа і його секрет, зʼєднані двокрапкою й закодовані в base64. На ключ, який API не може декодувати або не впізнає, він відповідає 401.

Генерування ключа

Створіть ключ у дашборді або через POST /api/v1/api_keys/ із сесії, у яку ви ввійшли і яка привʼязана до проєкту цього ключа. Дайте йому name, унікальне серед ваших ключів, і, за бажанням, description та expires_at. Відповідь містить ключ рівно один раз — у api_key, тож скопіюйте його одразу. Після цього API повертає назву, ролі, правила доступу й термін дії ключа, але ніколи — його секрет.

Привʼязка до проєкту

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

Проєкт — це одиниця керування доступом та ізоляції; білінг ведеться на рівні робочого простору. Для індивідуальної розробки достатньо проєкту за замовчуванням, який створюється разом із новим акаунтом; командам, що працюють із продакшном, зазвичай потрібен окремий проєкт для кожного середовища (prod, staging, dev), щоб скомпрометований dev-ключ не дістав до продакшн-даних.

Змінити проєкт = згенерувати новий ключ у цільовому проєкті. Механізму «використовуйте цей ключ, але вдавайте, що ви в іншому проєкті» немає: він підірвав би гарантію ізоляції.

Що може ключ

Ключ діє з ролями у своєму проєкті, а правила доступу обмежують, які виклики він може робити:

  • roles — ролі, з якими діє ключ, вибрані з тих, що ви маєте в проєкті. Якщо поле пропустити, ключ отримує їх усі.
  • access_rules — виклики, які може робити ключ. Кожне правило — це service (api для цього API), method і path, наприклад GET і /api/v1/instance/. GET /api/v1/api_keys/access_rules_artifacts перелічує всі методи й шляхи, які можна вказати; на шлях, якого не існує, створення ключа відповідає 422.
  • unrestricted: true — без правил доступу: ключ може робити будь-який виклик, який дозволяють його ролі.

Ключ без правил доступу й без unrestricted може лише прочитати власну сесію (GET /api/v1/account/get_session_auth_data). Виклик поза правилами доступу ключа отримує 403 з повідомленням «API key is restricted for this path!». Тож можна без зайвих витрат почати з вузьких правил і додавати виклики лише тоді, коли якийсь відхилено.

Ротація

Окремого виклику для ротації немає. Щоб замінити ключ, створіть новий, переведіть на нього свої інструменти, а потім видаліть старий через DELETE /api/v1/api_keys/{api_key_id}. API перевіряє ключ у кожному запиті, тож видалений ключ перестає працювати вже на наступному виклику. Інструменти, які тримають ключ довго (CI/CD, розгорнуті агенти), мають перечитувати його під час запуску процесу, щоб ротація поширювалася за один цикл розгортання. Задавайте ключам expires_at, щоб забутий ключ сам перестав працювати.

Якщо підозрюєте, що ключ скомпрометовано, одразу видаліть його — у дашборді або через DELETE /api/v1/api_keys/{api_key_id} із сесії, у яку ви ввійшли.

Типові помилки

API Webhooks і Inboxes відповідають на проблему з обліковими даними такими кодами. Вони відрізняються в одному: invalid_credential, тобто ключ, якого API не розпізнає, — це 403 у Webhooks і 401 в Inboxes.

Статусerror.codeAPIЩо це означає
401unauthorizedОбидваОблікові дані не надіслано (ні Authorization, ні X-API-Key), або ключ відкликано.
401 / 403invalid_credentialОбидваКлюч або токен недійсний: 401 в Inboxes, 403 у Webhooks. Замініть його: повторне надсилання не допоможе.
403forbiddenОбидваКлюч дійсний, але цього не може: бракує області дії чи ролі, ключ, обмежений певними проєктами, використано поза ними або продукт не ввімкнено для вашого робочого простору.

message пояснює, який саме випадок стався; розгалужуйте обробку за code, а не за статусом: invalid_credential — це 403 у Webhooks і 401 в Inboxes. Обробляйте його разом з unauthorized як «ці облікові дані не годяться».

Попередні версії цієї сторінки наводили no_credentials, invalid_credentials, expired_credentials, scope_required і wrong_project. API ніколи не надсилали цих кодів. Вони надсилають unauthorized там, де сторінка писала no_credentials; invalid_credential там, де вона писала invalid_credentials або expired_credentials, бо прострочений ключ — це ключ, який API не може перевірити; і forbidden там, де вона писала scope_required або wrong_project.

Помилки вище мають стандартний формат, описаний на сторінці Помилки.

Що далі

  • Прочитайте сторінку Угоди про правила, яких дотримується кожен ендпоінт (ідентифікатори ресурсів, пагінація, помилки, ідемпотентність).
  • Прочитайте довідник Віртуальні машини — конкретний розібраний приклад API ресурсу.