# Access, keys and privacy ## Keys - A project gets keys after its application is approved: [how access works](/access/). Keys are created in the [developer cabinet](https://app.ibusisrael.online/developers) and shown once. - Format: `ibk_live_k_<10 characters>_<43 characters>` (`ibk_test_…` for testing). The part before the last `_` is a public prefix you see in the cabinet and in refusals; the rest is secret. - Send the key only in a header: `Authorization: Bearer `. A key in the URL is refused (`KEY_IN_QUERY`) and should be replaced, because URLs end up in logs. - Keep keys on servers: not in web pages, mobile app packages, service workers or public repositories. A page or an app calls your server; your server calls iBus. - Rotation: create the new key and the old one keeps working for up to 24 hours. Revoke a leaked key at once. ## IP addresses A project may accept requests only from listed addresses (IPv4, IPv6, networks). Then a request needs both the right key and an allowed address (`IP_NOT_ALLOWED` otherwise, with `ip_seen`). To see the address the server sees: ```bash curl -H "Authorization: Bearer $IBUS_API_KEY" https://api.ibusisrael.online/api/access/whoami ``` The answer shows `ip_seen` and `checks` in the order the server applies them: the secret, the key, the project, the address (`allowed`, `denied` or `not_configured`). A refusal stops at the first failing check and shows only its code, the key prefix and `ip_seen`. It costs no data quota and is limited to 30 calls per minute. ## Refusal codes Each refusal has `code`, a short `detail`, `docs` (a link to this table) and `request_id`. Quote `request_id` when you write to iBus. | code | HTTP | What it means and what to do | |---|---|---| | `KEY_REQUIRED` | 401 | This address needs a key. Send `Authorization: Bearer `; request access if you have none. | | `KEY_INVALID` | 401 | The key is unknown or mistyped. Copy it again from the developer cabinet; repeated wrong keys from one network are restricted for a while. | | `KEY_REVOKED` | 401 | The key was revoked (by you, after a rotation or by iBus). Create a new key in the cabinet. | | `KEY_EXPIRED` | 401 | The key's validity date has passed. Create a new key. | | `KEY_IN_QUERY` | 400 | A key or token was found in the URL. Keys go only in the `Authorization` header; a key that was in a URL should be replaced. | | `KEY_NOT_ACCEPTED_HERE` | 401 | A key was sent to an address other than api.ibusisrael.online (for example the app's own address). Keys are checked only at https://api.ibusisrael.online — send the request there; elsewhere a key is refused, never ignored. | | `GROUP_NOT_ALLOWED` | 403 | Your project has no access to this group of operations. Ask for it from the project page. | | `OPERATION_NOT_AVAILABLE` | 403 | The operation is not public, or needs an approved project. | | `IP_NOT_ALLOWED` | 403 | The key is right, but the request came from an address that is not on the project's list. The answer shows `ip_seen`: the address the server saw. | | `PROJECT_SUSPENDED` | 403 | The project is paused by iBus. The reason is on the project page; keys keep their state. | | `PROJECT_BLOCKED` | 403 | The project is blocked and its keys are revoked. The reason is on the project page; you can reply there. | | `ACCESS_EXPIRED` | 403 | The project's access period has ended. Ask for an extension from the project page. | | `PLATE_LOOKUP_NOT_ALLOWED` | 403 | Looking up a vehicle by its licence plate is not available to your project. Vehicles appear under daily pseudonyms. | | `RATE_LIMITED` | 429 | Too many requests per minute: of your project (with a key) or of your network (without a key). Wait `Retry-After` seconds. | | `QUOTA_EXCEEDED` | 429 | The day, month or heavy-request budget of the project is used up. `scope` says which; `Retry-After` says when it resets. | | `CONCURRENCY_LIMIT` | 429 | Too many requests of the project at the same time. Wait for answers before sending more. | | `TEMPORARILY_RESTRICTED` | 429 | Requests are paused for a short time after repeated violations (for example many wrong keys). Wait `Retry-After`. | | `CAPACITY_RESERVED` | 503 | The service is busy and keeps capacity for passengers. Retry after `Retry-After` seconds. | | `POLICY_UNAVAILABLE` | 503 | Access rules cannot be checked right now, so keyed requests are refused rather than let through. Retry shortly. | | `EXTERNAL_PAUSED` | 503 | iBus has paused external integrations for a while (an incident or maintenance). Retry after `Retry-After`; your keys and limits are unchanged. | | `BODY_TOO_LARGE` | 413 | The request body is larger than allowed. Read operations need no body. | ## Not part of this API - Accounts, sign-in, favourites, settings, notifications and the Lior assistant: functions of the iBus app at `app.ibusisrael.online`, tied to its session. - The trip planner, walking paths, the whole network at once and vehicle positions: only for projects that need them, on request. Vehicles appear under daily pseudonyms; licence plates are not given out. - Older paths of `api.ibusisrael.online` (for example `/api/stops/search` without `/transport`) keep working for existing integrations; new integrations use `/api/transport/`. ## Browsers and CORS Cross-origin browser requests are allowed only for the iBus web app (`https://app.ibusisrael.online`), without cookies. Keys are not for browsers: a page on another site calls its own server. ## What the server keeps - For each request: the time, project, key prefix, operation, status, duration and the network part of the address (the last part is removed). Details are kept for 7 days, then only counts. - The key itself is never stored (only a hash) and never written to logs, reports or messages. - The API sets no cookies. Answers contain no personal data; vehicles appear under daily pseudonyms. ## Contact Questions and problem reports: [ibusisrael.online/contact](https://ibusisrael.online/contact). About a refusal, quote its `request_id`.