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. Подтвердите удаление.

После удаления ключ немедленно перестаёт работать. Все приложения, использующие этот ключ, будут получать ошибки аутентификации.