Access, keys and privacy

Keys#

A project gets keys after its application is approved: how access works. Keys are created in the developer cabinet 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 <key>. 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:

curl

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 <key>`; 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. About a refusal, quote its request_id.