Аутентификация
Как передавать ключ и когда он перестаёт действовать.
Каждый запрос к API подписывается ключом. Ключ выпускается в разделе «API» панели и принадлежит аккаунту: запросы с ним видят и меняют только объекты этого аккаунта.
Передача ключа
Ключ передаётся в заголовке Authorization по схеме Bearer:
GET /app/v1/account HTTP/1.1
Host: api.skystream.su
Authorization: Bearer sky_...Другие способы не принимаются. Ключ в строке запроса (?api_key=...) отклоняется с ошибкой api_key_in_query, даже если он верный: строка запроса сохраняется в журналах прокси-серверов и в истории браузера. Такой ключ следует считать раскрытым и заменить.
Куки API не читает. Сессия панели, открытой в том же браузере, на запросы к API не влияет.
Когда ключ не действует
Ключ проверяется при каждом запросе. Запрос отклоняется, если:
| Причина | Код | HTTP |
|---|---|---|
Заголовка Authorization нет | api_key_missing | 401 |
| Ключ не найден или передан не целиком | api_key_invalid | 401 |
| Ключ отозван | api_key_revoked | 401 |
| Срок ключа истёк | api_key_expired | 401 |
| Запрос пришёл с адреса не из списка IP ключа | ip_not_allowed | 403 |
| Доступ к API для аккаунта выключен | api_access_disabled | 403 |
| Доступ к панели для аккаунта закрыт | account_locked | 403 |
Выключение доступа к API и закрытие аккаунта действуют сразу на все ключи аккаунта. Когда доступ возвращают, прежние ключи снова начинают работать — если они не отозваны и их срок не истёк.
Неверные ключи
Запросы с неверным ключом считаются по адресу, с которого они пришли. После 20 таких запросов за 10 минут адрес блокируется, и API отвечает 429 too_many_invalid_keys с заголовком Retry-After — даже на запросы с верным ключом. Запрос с адреса не из списка IP ключа считается так же, как запрос с неверным ключом. Отозванные и истёкшие ключи в этот счёт не входят: забытая интеграция со старым ключом не блокирует адрес для нового.
Ключ, которым сделан запрос
GET /account возвращает в поле key сведения о ключе запроса: идентификатор, название, права, срок, суточный потолок трат и потраченное за сутки. По ним интеграция может проверить свои права при запуске, а не при первом отказе.