Автентифікація
API NimbusNexus на api.nimbusnexus.net приймає API-ключ у заголовку X-API-Key. Кожен ключ належить одній людині й працює в одному проєкті — з тими ролями й правилами доступу, з якими його створено.
Як виглядає запит
Надсилайте ключ у заголовку X-API-Key:
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.code | API | Що це означає |
|---|---|---|---|
| 401 | unauthorized | Обидва | Облікові дані не надіслано (ні Authorization, ні X-API-Key), або ключ відкликано. |
| 401 / 403 | invalid_credential | Обидва | Ключ або токен недійсний: 401 в Inboxes, 403 у Webhooks. Замініть його: повторне надсилання не допоможе. |
| 403 | forbidden | Обидва | Ключ дійсний, але цього не може: бракує області дії чи ролі, ключ, обмежений певними проєктами, використано поза ними або продукт не ввімкнено для вашого робочого простору. |
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 ресурсу.