Доступ, ключи и приватность
Ключи#
- Ключи проект получает после одобрения заявки: как устроен доступ. Ключи создаются в кабинете разработчика и показываются один раз.
- Формат:
ibk_live_k_<10 символов>_<43 символа>(ibk_test_…для проверки). Часть до последнего_- публичный префикс, его видно в кабинете и в отказах; остальное - секрет. - Передавайте ключ только в заголовке:
Authorization: Bearer <ключ>. Ключ в адресе запроса отклоняется (KEY_IN_QUERY), и его стоит заменить: адреса попадают в журналы. - Храните ключи на серверах: не на веб-страницах, не в пакетах мобильных приложений, не в service worker и не в публичных репозиториях. Страница или приложение обращается к вашему серверу, сервер - к iBus.
- Замена: создайте новый ключ, старый работает ещё до 24 часов. Утёкший ключ отзовите сразу.
IP-адреса#
Проект может принимать запросы только с перечисленных адресов (IPv4, IPv6, сети). Тогда запросу нужны и верный ключ, и разрешённый адрес (иначе IP_NOT_ALLOWED с ip_seen). Какой адрес видит сервер:
curl -H "Authorization: Bearer $IBUS_API_KEY" https://api.ibusisrael.online/api/access/whoamiВ ответе - ip_seen и checks в том порядке, в каком их применяет сервер: секрет, ключ, проект, адрес (allowed, denied или not_configured). Отказ останавливается на первой непройденной проверке и показывает только её код, префикс ключа и ip_seen. Квоту данных запрос не тратит, но ограничен 30 вызовами в минуту.
Коды отказов#
В каждом отказе есть code, короткий detail, docs (ссылка на эту таблицу) и request_id. Указывайте request_id, когда пишете в iBus.
| code | HTTP | Что значит и что делать |
|---|---|---|
KEY_REQUIRED | 401 | Для этого адреса нужен ключ. Передайте Authorization: Bearer <ключ>; если ключа нет, подайте заявку. |
KEY_INVALID | 401 | Ключ неизвестен или скопирован с ошибкой. Скопируйте его заново из кабинета разработчика; частые неверные ключи из одной сети временно ограничиваются. |
KEY_REVOKED | 401 | Ключ отозван (вами, после замены или командой iBus). Создайте новый ключ в кабинете. |
KEY_EXPIRED | 401 | Срок действия ключа закончился. Создайте новый ключ. |
KEY_IN_QUERY | 400 | В адресе запроса найден ключ или токен. Ключ передаётся только в заголовке Authorization; ключ, попавший в адрес, лучше заменить. |
KEY_NOT_ACCEPTED_HERE | 401 | Ключ отправлен не на api.ibusisrael.online (например, на адрес самого приложения). Ключи проверяются только на https://api.ibusisrael.online - отправьте запрос туда; на других адресах запрос с ключом отклоняется, а не выполняется без него. |
GROUP_NOT_ALLOWED | 403 | У проекта нет доступа к этой группе методов. Запросите её на странице проекта. |
OPERATION_NOT_AVAILABLE | 403 | Метод не публичный или доступен только одобренному проекту. |
IP_NOT_ALLOWED | 403 | Ключ верный, но запрос пришёл с адреса, которого нет в списке проекта. В ответе есть ip_seen - адрес, который увидел сервер. |
PROJECT_SUSPENDED | 403 | Проект приостановлен командой iBus. Причина указана на странице проекта; ключи сохраняются. |
PROJECT_BLOCKED | 403 | Проект заблокирован, его ключи отозваны. Причина указана на странице проекта, там же можно ответить. |
ACCESS_EXPIRED | 403 | Срок доступа проекта закончился. Попросите продление на странице проекта. |
PLATE_LOOKUP_NOT_ALLOWED | 403 | Поиск машины по номерному знаку проекту недоступен. Машины показываются под суточными псевдонимами. |
RATE_LIMITED | 429 | Слишком много запросов в минуту - у проекта (с ключом) или у вашей сети (без ключа). Подождите Retry-After секунд. |
QUOTA_EXCEEDED | 429 | Израсходован дневной, месячный или «тяжёлый» бюджет проекта. Какой именно - в scope; когда обновится - в Retry-After. |
CONCURRENCY_LIMIT | 429 | Слишком много одновременных запросов проекта. Дождитесь ответов, прежде чем отправлять новые. |
TEMPORARILY_RESTRICTED | 429 | Запросы временно приостановлены после повторных нарушений (например, многих неверных ключей). Подождите Retry-After. |
CAPACITY_RESERVED | 503 | Сервис загружен и бережёт ресурсы для пассажиров. Повторите через Retry-After секунд. |
POLICY_UNAVAILABLE | 503 | Правила доступа сейчас нельзя проверить, поэтому запросы с ключом отклоняются, а не пропускаются. Повторите чуть позже. |
EXTERNAL_PAUSED | 503 | iBus временно приостановил внешние интеграции (инцидент или работы). Повторите после Retry-After; ключи и лимиты не меняются. |
BODY_TOO_LARGE | 413 | Тело запроса больше допустимого. Методам чтения тело не нужно. |
Что не входит в этот API#
- Аккаунты, вход, избранное, настройки, уведомления и ассистент Лиор - функции приложения iBus на
app.ibusisrael.online, привязанные к его сессии. - Планировщик поездок, пешие пути, вся сеть сразу и положение машин - только проектам, которым это нужно, по запросу. Машины показываются под суточными псевдонимами; госномера не выдаются.
- Старые пути
api.ibusisrael.online(например,/api/stops/searchбез/transport) работают для существующих интеграций; новые интеграции используют/api/transport/.
Браузеры и CORS#
Кросс-доменные запросы из браузера разрешены только веб-приложению iBus (https://app.ibusisrael.online), без cookie. Ключи не для браузеров: страница другого сайта обращается к своему серверу.
Что хранит сервер#
- О каждом запросе: время, проект, префикс ключа, метод, статус, длительность и сетевая часть адреса (последняя часть удаляется). Подробно - 7 дней, дальше только счётчики.
- Сам ключ не хранится (только хеш) и не попадает в журналы, отчёты и сообщения.
- API не ставит cookie. В ответах нет персональных данных; машины - под суточными псевдонимами.
Связаться#
Вопросы и сообщения о проблемах: ibusisrael.online/contact. Об отказе - с его request_id.