Ключі API

Ключі API надають програмний доступ до REST API badges.ninja. Використовуйте їх, щоб автоматизувати створення, видачу та керування значками зі своїх застосунків.

Створення ключа API

1. Відкрийте сторінку API Keys на бічній панелі.
2. Натисніть Create API Key. Відкриється вбудована форма:

3. Вкажіть назву ключа й натисніть Create. Повний ключ відображається лише один раз у зеленому банері:

4. Негайно скопіюйте ключ — повний ключ показується лише один раз. Якщо ви його втратите, доведеться створити новий. Після закриття банера на панелі керування відображається лише префікс ключа (наприклад, bws_a1b2c3d4...); повний ключ зберігається на сервері й використовується для автентифікації ваших запитів:

У кожному рядку також вказано, коли ключ було створено, а після першого використання — позначку часу last used, щоб ви могли помітити застарілі ключі.

Області доступу

Створюючи ключ, ви можете зробити його лише для читання або залишити повний доступ:

Область	Дозволяє
Повний доступ (за замовчуванням)	Читання та запис — перегляд даних, а також створення, видача, оновлення чи видалення.
Лише читання	Тільки безпечні запити GET. Будь-який запит на зміну (POST, PUT, PATCH, DELETE) відхиляється з помилкою 403 Forbidden.

Використовуйте ключ лише для читання для інтеграцій, яким потрібно лише читати ваші дані (звітність, інформаційні панелі, резервні копії), щоб викрадений ключ нічого не міг змінити. Позначте Read-only key у формі створення; ключі лише для читання мають у списку позначку Read-only. Ключі, створені до появи областей доступу, зберігають повний доступ.

Формат ключа

Ключі API мають префікс bws_, за яким іде 32-символьний шістнадцятковий рядок:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Використання ключів API в запитах

Додавайте ключ API до заголовка X-Api-Key кожного запиту до API:

curl -X GET https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here"

Докладніше про автентифікацію в API читайте на сторінці Автентифікація.

Ліміти ключів за тарифом

Кількість ключів API, які ви можете створити, залежить від вашого тарифу:

Тариф	Ліміт ключів API
Free	1
Starter ($9/mo)	5
Pro ($29/mo)	20

Термін дії ключа

Кожен ключ API втрачає чинність через рік після створення. Щойно термін дії ключа спливає, він перестає автентифікувати запити — так само, як якби його було видалено. Створіть новий ключ до завершення терміну дії старого, щоб уникнути перебоїв.

Видалення ключа

1. Відкрийте сторінку API Keys.
2. Знайдіть ключ, який потрібно видалити.
3. Натисніть Delete.
4. Підтвердьте видалення.

Після видалення ключ одразу перестає працювати. Усі застосунки, що використовують цей ключ, отримуватимуть помилки автентифікації.