# Доступ, ключи и приватность ## Ключи - Ключи проект получает после одобрения заявки: [как устроен доступ](/ru/access/). Ключи создаются в [кабинете разработчика](https://app.ibusisrael.online/developers) и показываются один раз. - Формат: `ibk_live_k_<10 символов>_<43 символа>` (`ibk_test_…` для проверки). Часть до последнего `_` - публичный префикс, его видно в кабинете и в отказах; остальное - секрет. - Передавайте ключ только в заголовке: `Authorization: Bearer <ключ>`. Ключ в адресе запроса отклоняется (`KEY_IN_QUERY`), и его стоит заменить: адреса попадают в журналы. - Храните ключи на серверах: не на веб-страницах, не в пакетах мобильных приложений, не в service worker и не в публичных репозиториях. Страница или приложение обращается к вашему серверу, сервер - к iBus. - Замена: создайте новый ключ, старый работает ещё до 24 часов. Утёкший ключ отзовите сразу. ## IP-адреса Проект может принимать запросы только с перечисленных адресов (IPv4, IPv6, сети). Тогда запросу нужны и верный ключ, и разрешённый адрес (иначе `IP_NOT_ALLOWED` с `ip_seen`). Какой адрес видит сервер: ```bash 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](https://ibusisrael.online/contact). Об отказе - с его `request_id`.