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

Формат API key, варіанти заголовків, scope та практики безпеки для API Qamera AI.

Кожен запит до API Qamera AI повинен містити дійсний API key. Неавтентифіковані запити отримують відповідь 401 Unauthorized.

Формат API Key

Ключі мають такий формат:

mk_live_<keyId>.<secret>

Частина	Опис
`mk_live_`	Фіксований префікс, що вказує на робочий production-ключ.
`<keyId>`	Унікальний ідентифікатор ключа, що використовується для пошуку та аудиту.
`<secret>`	Секретна частина, що показується лише один раз під час створення.

Приклад:

mk_live_7f3a2b1c.kP9xmWqLzR4tNvYs

Передача ключа

Для автентифікації можна використовувати один з двох заголовків:

Заголовок X-Api-Key (рекомендовано)

curl -X GET https://qamera.ai/api/external/products \
  -H "X-Api-Key: mk_live_7f3a2b1c.kP9xmWqLzR4tNvYs"

Заголовок Authorization Bearer

curl -X GET https://qamera.ai/api/external/products \
  -H "Authorization: Bearer mk_live_7f3a2b1c.kP9xmWqLzR4tNvYs"

Обидва методи еквівалентні. Якщо присутні обидва заголовки, пріоритет має X-Api-Key.

Отримання API Key

Увійдіть у Qamera AI та відкрийте ваш командний робочий простір.
Перейдіть до Settings → API Keys.
Натисніть Generate New Key.
Негайно скопіюйте повне значення ключа. Секретна частина не зберігається у відкритому вигляді та не може бути відновлена пізніше.

Кожен командний акаунт може мати кілька активних ключів. Ключі прив'язані до акаунта, який їх створив, і наслідують баланс кредитів цього акаунта.

Scope

API key мають призначені scope, які контролюють, які операції вони можуть виконувати.

Scope	Дозволи
`content.register`	Створення замовлень, запуск генерації контенту (POST-ендпоінти).
`content.read`	Читання продуктів, замовлень, завдань та результатів (GET-ендпоінти).
`queue.nudge`	Зміна пріоритету завдань у черзі. Заплановано.

Наразі всі ключі видаються зі scope content.register. Запити до ендпоінта, що вимагає scope, якого ваш ключ не має, отримають відповідь 403 Forbidden.

Безпека

Хешоване зберігання — Секрети ключів хешуються за допомогою bcrypt перед збереженням. Qamera AI не може відновити втрачений секрет.
Ізоляція за акаунтами — Ключі належать конкретному командному акаунту. Вони не можуть отримати доступ до даних інших акаунтів.
Термін дії — Ключі можна налаштувати з терміном дії. Прострочені ключі повертають 401 Unauthorized.
Відкликання — Ви можете відкликати ключ у будь-який час через Settings → API Keys. Відкликання набуває чинності негайно.
Відстеження використання — Кожен ключ записує мітку часу last_used_at. Уся генерація контенту, ініційована ключем, відстежується через cg_orders та cg_jobs для аудиту.

Найкращі практики

Зберігайте ключі у змінних середовища або менеджері секретів. Ніколи не комітьте їх до системи контролю версій.
Використовуйте окремі ключі для різних середовищ (розробка, staging, production).
Регулярно ротуйте ключі та відкликайте ті, що більше не потрібні.
Моніторте last_used_at для виявлення невикористовуваних або потенційно скомпрометованих ключів.