Доступ и безопасность
Как хранить, передавать, проверять и заменять ключ Integration API.
Результат
После настройки ваша серверная часть сможет обращаться к Integration API, а тестовый ключ не попадёт в браузер, мобильное приложение, логи или исходный код.
Как передавать ключ
Добавляйте API-ключ в заголовок каждого серверного запроса:
Заголовок авторизации
Api-Key: yario_test_<public-id>.<secret>
Префикс yario_test_ или yario_live_ показывает среду. Полное значение ключа кабинет показывает только один раз.
Проверьте ключ безопасным запросом:
Проверка ключа
GET /v1/me HTTP/1.1
Host: integration-api.yario.ai
Api-Key: yario_test_...
Готово, если: ответ содержит нужную среду и список разрешений вашего ключа.
Что разрешает ключ
Разрешения ключа называются scopes:
| Разрешение | Что можно делать |
|---|---|
tickets:read | Читать доступные обращения |
tickets:write | Создавать и изменять обращения |
messages:read | Читать сообщения |
messages:write | Добавлять сообщения и вложения |
merchant_onboarding:read | Читать анкеты мерчантов |
merchant_onboarding:write | Возвращать результат KYC-проверки |
Для доступа одновременно должны выполняться два условия: нужный раздел API включён для подключения, а ключ имеет соответствующее разрешение. Например, одного merchant_onboarding:read недостаточно, если проверка мерчантов не подключена для этой компании.
Где хранить ключ
- храните его в менеджере секретов или защищённых переменных окружения серверного приложения;
- не добавляйте ключ в JavaScript браузера, мобильное приложение или публичный репозиторий;
- не передавайте ключ в URL;
- исключите заголовок
Api-Keyиз логов, трассировки и аналитики; - используйте разные ключи для тестовой и рабочей среды.
Как заменить ключ без остановки интеграции
- Выпустите новый ключ с теми же необходимыми разрешениями.
- Сохраните его, не отключая старый.
- Переключите серверное приложение на новый ключ.
- Проверьте запрос
/v1/me. - Отзовите старый ключ.
- Убедитесь, что старый ключ получает
401.
При подозрении на утечку прекратите использование ключа и отзовите его как можно быстрее.
Что означают ошибки доступа
401— ключ отсутствует, неверен, истёк или отозван;403— ключ действителен, но у него нет нужного разрешения или раздел API не подключён.
OAuth
OAuth в текущей версии не поддерживается. Не передавайте API-ключ в заголовке Authorization: Bearer и не добавляйте лишний OAuth-сценарий. Используйте заголовок Api-Key ровно так, как показано выше.
Навигация: начало работы · регистрация · обращения и сообщения · описание API · тестирование