Glossary

Reference of key terms you will encounter when working with the Bikeep API.

Core Concepts

Location

A physical site where Bikeep hardware is installed. Every location has a type (e.g., BIKE_LOCKERS, BIKE_HOUSE) that determines what kind of devices it contains and how they behave. Locations belong to an operator and are identified by a UUID id.

API: GET /location/v1/locations

Device

An individual controllable hardware unit. Devices are the things you send commands to — a single locker, a bike room entrance door, or a bike dock. Each device has a type, a state, and responds to commands asynchronously.

API: GET /device/v1/locations/{location_id}/devices

Command

An asynchronous instruction sent to a device. Commands are not instant — they travel from the Bikeep backend to IoT hardware and back. Every command’s state.value progresses through: NOT_SENT → SENT → RECEIVED → SUCCESS (or ERROR). The NOT_SENT → SENT transition is near-instant, so most POST responses already show SENT. You must poll the command status to know when it completes.

API: POST /device/v1/devices/{device_id}/commands

Session

A usage record that tracks a device interaction from reservation through active use to completion. Sessions have statuses (pending, booked, active, ended), track timing, user identity, fees, and payment. Session tracking requires the External Users authentication method; the S2S OAuth2 method does not create sessions.

API: GET /session/v2/sessions

See Sessions for the full lifecycle.

Hardware Terms

Locker

An individual enclosed storage unit. In the API, a locker is a device with type: LOCKER. Each locker can be independently locked, unlocked, booked, and monitored. Lockers are found at locations with type: BIKE_LOCKERS or inside a bike house (BIKE_HOUSE).

Bike House (Bike Room)

A collective enclosed space — a bike room or bike hangar — secured by one or more entrance doors. In the API, a bike house is a location with type: BIKE_HOUSE, BIKE_HOUSE_DOCKLESS, or BIKE_HANGAR. A bike house may contain interior storage devices — either individual lockers or bike docks — inside.

Guard (IoT Gateway)

An IoT gateway and parent controller device. In the API, a guard is a device with type: GUARD. The GUARD bridges all child devices (BIKE_HOUSE_DOOR, LOCKER, DOCK, etc.) to the Bikeep cloud via MQTT and stores/distributes allowlists (RFID access keys) to all its children. Present at all location types, not just bike houses. The only command available is take-photo (if a camera is connected). The GUARD has no door-control commands — physical door access is handled by the BIKE_HOUSE_DOOR device.

BIKE_HOUSE_DOOR (Entrance Door)

A physical entrance door device at a bike house. In the API, a door is a device with type: BIKE_HOUSE_DOOR (devices not yet synced with hardware may report type: DOOR — treat the same). It is a child of the GUARD and controls the electronic lock on one of the bike house’s entry points. A bike house may have one or more BIKE_HOUSE_DOORs — one per physical entrance. The door opens when a whitelisted RFID card is tapped on its reader, or via the API unlock command. The lock re-engages automatically when the door closes or a timeout expires.

Dock

An outdoor bicycle parking unit. In the API, a dock is a device with type: BIKE_DOCK. You may also encounter type: DOCK — a functionally equivalent type alias with the same commands and state machine. Docks are found at locations with type: BIKE_DOCKS. See Device Types — BIKE_DOCK for details.

Heartbeat

A periodic signal from a device indicating it is online. The heartbeat_v2 object on each device provides the current health assessment: HEALTHY (communicating normally), UNHEALTHY (heartbeat delayed ~15 s), DEAD (no heartbeat ~30 s), or LONG_DEAD (offline 2+ hours). The top-level heartbeat_health field is deprecated — it does not distinguish LONG_DEAD from DEAD.

See Device Types — Common Properties for the full heartbeat_v2 object.

Connection (Location)

A location-level connectivity indicator. The connection field on a location response shows the aggregate status of its devices: online (all devices communicating), partially_online (some devices offline), offline (no devices communicating), or unknown (status not yet determined). Use this for monitoring dashboards and alerting.

Sleep State

The sleep_state field on a device indicates its current power-saving mode: "" (empty string — awake), LIGHT_SLEEP, or DEEP_SLEEP. The sleep state is tightly coupled with the device’s power save strategy: LIGHT_SLEEP only occurs on REMOTE_WAKEUP devices, and DEEP_SLEEP only occurs on LOCAL_WAKEUP devices. A device in DEEP_SLEEP cannot be reached via the API — it must be woken by physical interaction (e.g., RFID tap).

See Device Types — Power Save and Sleep for strategy comparison tables and integrator guidance.

Power Save Strategy

The power_save_strategy field describes how a device wakes from sleep. Three values are possible:

• NONE — device is always on, no sleep mode
• REMOTE_WAKEUP — backend wakes the device transparently when you send a command (only enters LIGHT_SLEEP). No code changes needed — just expect higher latency while waking
• LOCAL_WAKEUP — device can only be woken by physical interaction such as an RFID tap or button press (may enter DEEP_SLEEP). API commands will not reach the device while sleeping

See Device Types — Power Save and Sleep for the full behavioral breakdown.

Allowlist Terms

Whitelist (Allowlist)

A named list that connects RFID cards (entities) to devices or locations (targets). Whitelists use a many-to-many model: one whitelist can contain many RFID cards and apply to many devices. A device can have up to 3 whitelists by default.

API: GET /whitelist/v1/whitelists

Entity

An entry in a whitelist representing an RFID card. Each entity has:

• id — the RFID card identifier (raw lowercase hex, even length, max 20 characters — e.g., 04a2b3c4d5e6f7)
• id_type — always rfid
• status — ACTIVE, INACTIVE (disabled by administrator), or EXPIRED
• expires_at — optional expiration time (RFC 3339)
• is_master_key — when true, the card can unlock any occupied device (see Master Key)

API: POST /whitelist/v1/whitelists/{whitelist_id}/entities

Target

A device or location that a whitelist applies to. Targets have:

• id — the device or location UUID
• type — device or location
• keys_only — when true, syncs the whitelist RFID keys to the device’s local storage for offline access. Used for GUARD devices (bike room entrance doors) so RFID access works reliably even when the device is temporarily offline

API: POST /whitelist/v1/whitelists/{whitelist_id}/targets

Master Key

A whitelist entity flag (is_master_key: true) that allows an RFID card to unlock any occupied device at the targeted location. This is used for scenarios where a user needs to unlock whichever device is available. The master key privilege can be time-limited using expires_at.

Public Area

Public areas group locations for public-facing queries — e.g., availability widgets or map displays. Querying GET /location/v1/public-areas/{id}/locations returns all locations within the area without requiring authentication.

API: GET /location/v1/public-areas

Webhook

An event notification pushed from Bikeep to your server when something changes — a device goes offline, an alarm triggers, etc. Webhook delivery is aggregated by default (intervals vary by type: alarm ~1 min, connection ~5 min, status ~5 min). Direct delivery with sub-second latency is available on request. Event types include alarm, connection, status, and connection_confirmed.

API: See the Webhooks Reference.

Device States

Note: Maintenance and out-of-service status is tracked at the location level via location_status, not as a device state.

See State Machines for full transition diagrams.

Authentication Methods

See Authentication for detailed setup instructions.