Авторизация API#
В этой инструкции вы узнаете, как настроить авторизацию API в КриптоАРМ Server, ознакомитесь с доступными режимами (none и apikey), научитесь передавать API-ключи различными способами, а также получите практические примеры запросов и рекомендации по безопасной эксплуатации.
Содержание:
- Режимы авторизации
- Настройка авторизации
- Использование API
- Примеры запросов
- Рекомендации по безопасности
- Ошибки авторизации
- Использование API ключей в Swagger UI
Режимы авторизации#
Сервис поддерживает два режима авторизации для доступа к REST API:
| Режим | Описание |
|---|---|
none | Авторизация отключена. Все запросы к API выполняются без проверки |
apikey | Доступ к API разрешен только при наличии корректного API ключа |
Выбор режима определяется переменной окружения AUTH_MODE.
Настройка авторизации#
Переменные окружения#
# Режим авторизации: "none" или "apikey"
AUTH_MODE=none
# Список API ключей через запятую (используется только при AUTH_MODE=apikey)
API_KEYS=your-api-key-1,your-api-key-2,your-api-key-3
Параметры#
| Переменная | Описание |
|---|---|
AUTH_MODE | режим авторизации (none или apikey) |
API_KEYS | список допустимых API ключей через запятую |
Примеры конфигурации#
Авторизация отключена#
В этом режиме все запросы выполняются без проверки ключей.
Авторизация по API ключу#
В этом режиме каждый запрос к API должен содержать корректный API ключ.
Использование API#
API ключ можно передать несколькими способами.
Заголовок X-API-Key (рекомендуется)#
Этот способ является предпочтительным при интеграции с внешними системами.
Заголовок Authorization: Bearer#
Подходит для клиентов, использующих стандартный механизм Bearer-токенов.
Query-параметр#
Этот способ можно использовать для тестирования, однако его не рекомендуется применять в production-среде.
Примеры запросов#
JavaScript/Node.js#
// Используя fetch
const response = await fetch('http://localhost:3037/api/endpoint', {
headers: {
'X-API-Key': 'your-api-key-1'
}
});
// Используя axios
const response = await axios.get('http://localhost:3037/api/endpoint', {
headers: {
'X-API-Key': 'your-api-key-1'
}
});
Python#
import requests
headers = {
'X-API-Key': 'your-api-key-1'
}
response = requests.get('http://localhost:3037/api/endpoint', headers=headers)
Рекомендации по безопасности#
При использовании API ключей рекомендуется соблюдать следующие меры безопасности:
- используйте длинные и случайные ключи;
- не передавайте API ключи в URL параметрах;
- не сохраняйте ключи в публичных репозиториях;
- регулярно выполняйте ротацию ключей;
- используйте HTTPS при работе в production-среде.
Ошибки авторизации#
| Код | Описание |
|---|---|
401 Unauthorized | API ключ отсутствует или указан неверно |
403 Forbidden | API ключ недействителен или не имеет доступа |
Использование API ключей в Swagger UI#
Swagger UI автоматически поддерживает авторизацию API ключами.
Если включен режим:
в интерфейсе Swagger отображается кнопка Authorize.
Чтобы авторизоваться:
- Нажмите Authorize в правом верхнем углу интерфейса.
- Введите API ключ в поле X-API-Key или Bearer.
- Нажмите Authorize.
После этого Swagger будет автоматически добавлять ключ ко всем API-запросам.
Если режим авторизации отключен (AUTH_MODE=none) или API ключи не настроены, кнопка Authorize в Swagger UI не отображается.