Bike House (Dockless) Integration

This bike room access control API guide covers integration with Bikeep dockless bike houses — enclosed spaces with controlled door access and no interior storage devices. Users enter through a BIKE_HOUSE_DOOR, park their bike freely on the floor or in non-electronic racks, and leave. The API integration is access-control only: manage who can open the door.

This guide covers two location types:

• BIKE_HOUSE_DOCKLESS — an indoor bike room with no docks or lockers inside
• BIKE_HANGAR — an outdoor enclosed structure (like a shelter or shipping container) with the same access-control model

Both use the same API — the only difference is physical form factor.

Need interior device management too? If your bike house contains lockers or bike docks inside, see Bike House (with Docks/Lockers) Integration instead.

Prerequisites:

• API credentials (client ID and secret) from Bikeep
• Familiarity with Device Types (GUARD, BIKE_HOUSE_DOOR) and Location Types (BIKE_HOUSE_DOCKLESS, BIKE_HANGAR)

Step 0: Authenticate

Obtain an OAuth2 access token using the client credentials flow:

curl -X POST https://auth.bikeep.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Use the returned access_token in the Authorization: Bearer {token} header for all subsequent requests. Tokens expire after 1 hour. See Authentication for all auth methods and refresh details.

Architecture

A dockless bike house is a location that contains only a gateway and one or more entrance doors — no interior storage devices:

BIKE_HOUSE_DOCKLESS / BIKE_HANGAR (Location)
├── GUARD (Device)              — IoT gateway (parent controller, allowlist storage)
├── BIKE_HOUSE_DOOR (Device)    — entrance door #1 (RFID reader + electronic lock)
└── BIKE_HOUSE_DOOR (Device)    — entrance door #2 (if multiple entrances)

The GUARD is the IoT gateway — it bridges the BIKE_HOUSE_DOOR devices to the cloud and distributes allowlists. Each BIKE_HOUSE_DOOR is a physical entrance that users interact with. There are no interior devices to manage — users park freely inside the space.

Note: Some locations have more than one GUARD. This can happen when doors are too far apart for a single controller’s wiring, or the location’s physical layout requires separate gateways. When listing devices, filter for type: "GUARD" — do not assume exactly one per location.

How this compares to a bike house with docks/lockers

Both variants share: GUARD gateway, one or more BIKE_HOUSE_DOOR entrances, RFID + API access models, automatic door re-locking.

Step 1: Discover Locations

curl https://services.bikeep.com/location/v1/locations \
  -H "Authorization: Bearer {token}"

Filter results for type: "BIKE_HOUSE_DOCKLESS" or type: "BIKE_HANGAR". Both types use the same API flow — the difference is physical form factor only:

• BIKE_HOUSE_DOCKLESS — indoor room (e.g., ground floor of a residential building)
• BIKE_HANGAR — outdoor enclosed structure (e.g., a shelter or shipping container in a parking lot)

Step 2: List Devices — Identify the Gateway and BIKE_HOUSE_DOOR(s)

curl https://services.bikeep.com/device/v1/locations/{location_id}/devices \
  -H "Authorization: Bearer {token}"

Response:

{
  "data": [
    {
      "id": "guard-uuid-0000-0000-000000000001",
      "type": "GUARD",
      "alias": "C1",
      "code": "123456",
      "state": {
        "value": "LOCKED",
        "changed_at": "2025-12-15T09:00:00Z"
      },
      "hardware_state": "NORMAL",
      "heartbeat_health": "HEALTHY"
    },
    {
      "id": "door-uuid-0000-0000-000000000001",
      "type": "BIKE_HOUSE_DOOR",
      "alias": "D1",
      "code": "123457",
      "state": {
        "value": "LOCKED",
        "changed_at": "2025-12-15T09:00:00Z"
      },
      "hardware_state": "NORMAL",
      "heartbeat_health": "HEALTHY"
    },
    {
      "id": "door-uuid-0000-0000-000000000002",
      "type": "BIKE_HOUSE_DOOR",
      "alias": "D2",
      "code": "123460",
      "state": {
        "value": "LOCKED",
        "changed_at": "2025-12-15T09:00:00Z"
      },
      "hardware_state": "NORMAL",
      "heartbeat_health": "HEALTHY"
    }
  ]
}

Note: The GUARD’s state field is present in the response but is not operationally meaningful — do not use it to determine bike house status. Monitor heartbeat_v2.health instead for gateway connectivity.

Notice: only GUARD and BIKE_HOUSE_DOOR devices — no lockers or docks. This is the defining characteristic of a dockless bike house.

• GUARD — the IoT gateway (parent controller). Not user-facing; manages cloud connectivity and allowlist distribution.
• BIKE_HOUSE_DOOR — a physical entrance door. A bike house may have multiple doors (one per entry point). Users tap RFID cards here, and you can send the unlock command to open it remotely. Filter devices for type: "BIKE_HOUSE_DOOR" to find all entrances.

Note: Devices may report type: "DOOR" if not yet synced with hardware — treat these the same as BIKE_HOUSE_DOOR.

Step 3: Door Access

Bike house entrances are controlled by BIKE_HOUSE_DOOR devices (children of the GUARD gateway). Users can access the bike room via RFID card tap and/or the API unlock command.

What happens physically:

1. The user taps their whitelisted RFID card on a door’s reader — and/or your app sends an unlock command to the specific BIKE_HOUSE_DOOR device
2. The electronic lock releases
3. The user pulls the door open and enters
4. The door closes behind them and the lock re-engages automatically

How integrators manage access: There are two access models, and you can use either or both:

• API-only access — your app sends unlock commands to specific BIKE_HOUSE_DOOR devices (e.g., a “tap to unlock” button in your mobile app). No allowlist setup needed.
• RFID card access — users tap physical RFID cards on the door reader. You manage cards via the Whitelist API. See Step 5: Allowlist Architecture below.

Most integrations use API-only access. Add RFID card access if your users need to enter the bike room without the app (e.g., dead phone, offline access).

For remote door access (e.g., from a mobile app), send the unlock command to the specific BIKE_HOUSE_DOOR device:

curl -X POST \
  https://services.bikeep.com/device/v1/devices/{door_device_id}/commands \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"command": "unlock"}'

Response:

{
  "uri": "/device/v1/commands/{command_id}",
  "id": "{command_id}",
  "name": "unlock",
  "device": {
    "id": "{door_device_id}",
    "uri": "/device/v1/devices/{door_device_id}"
  },
  "state": {
    "value": "SENT",
    "timeout_at": "2026-02-26T10:00:03.000Z"
  },
  "events": [
    {
      "name": "REQUEST_INITIATED",
      "timestamp": "2026-02-26T10:00:00.000Z"
    }
  ]
}

Poll GET /device/v1/commands/{command_id} until state.value reaches SUCCESS (or ERROR). The door lock releases on success — the user can then pull the door open. Typical round-trip: 1–5 seconds.

Multi-door bike houses: Some bike houses have multiple entrance doors. Filter the location’s devices for type: "BIKE_HOUSE_DOOR" and use the alias field (e.g., “D1”, “D2”) or device metadata to determine which door to unlock. Allowlists are distributed to all doors automatically — RFID access works at every entrance without per-door configuration.

Step 4: Complete User Flow

The user flow for a dockless bike house is simple — there are no interior devices to manage:

1. Enter the bike room — User taps RFID card on a BIKE_HOUSE_DOOR reader (and/or app sends unlock to the BIKE_HOUSE_DOOR device) → door opens → user enters
2. Park freely — User parks their bike on the floor, a rack, or any available space inside. No API interaction needed.
3. Leave the bike room — Most entrance doors allow exit without RFID (exit button or push bar)

Later, to retrieve the bike:

4. Re-enter the bike room — User taps RFID card on a BIKE_HOUSE_DOOR reader (and/or app sends unlock)
5. Take their bike and leave — Exit the room

That’s it. The entire API integration is about door access control — who can enter and when.

Step 5: Allowlist Architecture (Optional — RFID Access)

Skip this step if your integration uses only the API unlock command (e.g., mobile app button). Allowlists are only needed when users will access the bike room by tapping physical RFID cards on the door reader. You can also combine both models — e.g., RFID cards for regular commuters and API commands for app-based visitors — on the same bike house.

Allowlists for dockless bike houses follow a GUARD-distributes-to-children model. Since the only children are BIKE_HOUSE_DOORs, this means targeting the GUARD once grants RFID access to every entrance.

How allowlist distribution works

Allowlists target the GUARD (or location), and the GUARD distributes keys to ALL its children — in a dockless bike house, that means all BIKE_HOUSE_DOOR devices.

You target the GUARD or location once, and access is automatically distributed to every door. You do NOT need to create separate allowlists for each BIKE_HOUSE_DOOR.

Multi-GUARD locations: If a location has more than one GUARD, targeting the location covers all GUARDs and their children automatically. If you target a specific GUARD device instead, only that GUARD’s children receive the keys.

Setting up access

Note: Whitelists and their targets are configured by Bikeep during station provisioning. As an integrator, you use the API to manage entities (RFID cards) on the existing whitelist — adding and removing cards as users gain or lose access.

# Discover existing whitelists for the location
curl https://services.bikeep.com/whitelist/v1/locations/{location_id}/whitelists \
  -H "Authorization: Bearer {token}"

Use the whitelist id from the response to add or remove RFID cards. For detailed entity management (entity statuses, batch operations, removing cards), see Locker & Dock Integration — Step 4.

# 1. Add RFID cards
curl -X POST \
  https://services.bikeep.com/whitelist/v1/whitelists/{whitelist_id}/entities \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "ADD",
    "entities": [
      {
        "id": "04a2b3c4d5e6f7",
        "id_type": "rfid",
        "status": "ACTIVE",
        "comment": "User Alice"
      }
    ]
  }'

Step 6: Monitor Bike Room State

Door state

Each BIKE_HOUSE_DOOR device primarily alternates between LOCKED and UNLOCKING:

• LOCKED — door is secured (this is the “available” state for BIKE_HOUSE_DOOR devices)
• UNLOCKING — door lock is releasing

If the bike house has multiple BIKE_HOUSE_DOORs, each reports its state independently.

The GUARD (IoT gateway) also reports state and heartbeat data, but its state is not operationally meaningful — monitor the GUARD’s heartbeat_v2.health to assess gateway connectivity. The legacy heartbeat_health field is deprecated and does not distinguish LONG_DEAD from DEAD.

Each BIKE_HOUSE_DOOR also reports its own heartbeat_v2.health (derived from the GUARD). When interacting with a specific door — for example, before sending an unlock command — check that door’s health to confirm it is reachable.

# All devices at the location
curl https://services.bikeep.com/device/v1/locations/{location_id}/devices \
  -H "Authorization: Bearer {token}"

# A specific device
curl https://services.bikeep.com/device/v1/devices/{device_id} \
  -H "Authorization: Bearer {token}"

Location health

The location itself reports a connection field for overall site health:

Use the location’s connection field as a high-level health indicator (e.g., a green/yellow/red status in your UI).

Availability

Dockless bike houses have no interior storage devices to count. Availability is not available through the API — there is no interior device count and no capacity data. The devices.available count on the location response reflects BIKE_HOUSE_DOOR availability (doors that are online and ready to accept an unlock), not parking spots.

Important Notes

• GUARD is not a door: The GUARD is the IoT gateway (parent controller). It stores and distributes allowlists but has no door-control commands. To open a door, send the unlock command to the specific BIKE_HOUSE_DOOR device.
• No session tracking: Dockless bike houses do not generate usage sessions — there are no interior devices to detect check-in/check-out activity. If your use case requires session data, consider a bike house with interior devices where individual lockers or docks create sessions.
• Tailgating / piggybacking: Users can enter the bike house without triggering a door unlock event — for example, by following another user through an open door, entering as someone leaves, or finding the door propped open. Since dockless hubs have no interior devices, the API has no way to detect these entries. Do not assume that every door unlock event corresponds 1:1 with a user entry, or that the system sees every person inside the space.
• RFID format (if using RFID cards): RFID card IDs must be raw lowercase hexadecimal with no separators, even length (e.g., 04a2b3c4d5e6f7 — 14 characters). Do not use colons or uppercase. Maximum 20 characters.
• Re-adding an entity: If you ADD an RFID card that already exists in the whitelist, the existing entry is replaced (upsert). This is useful for updating fields like status, expires_at, or comment without needing to REMOVE first.
• Batch error handling: Entity and target modification endpoints process items individually. If some items succeed and others fail, the response is 400 with an error_results array listing only the failed items. Successfully processed items are not rolled back.
• Webhooks: Bikeep supports webhook notifications for device events and connectivity changes. See Webhooks for setup, payload format, and delivery options.