Quickstart

Get your first Bikeep API response in under 5 minutes. By the end, you will have authenticated, listed your locations, found a device, and sent a command.

You need: A client_id, client_secret, and operator_id from Bikeep. Don’t have credentials yet? Request them.

1. Get an Access Token

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"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Copy the access_token value. You’ll use it in every subsequent request.

2. List Your Locations

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

Response (abbreviated):

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "BIKE_LOCKERS",
      "name": "#1234 Office Building A",
      "status": "LAUNCHED",
      "connection": "online",
      "devices": {
        "total": 10,
        "available": 7,
        "online": 10
      }
    }
  ]
}

Note the id of a location — you’ll need it next.

Different hardware? Your response may show BIKE_DOCKS, BIKE_HOUSE, or other location types depending on your hardware. This quickstart works with any type. For product-specific guidance, see Locker & Dock Integration, Bike House (Dockless), or Bike House (with Docks/Lockers).

3. List Devices at a Location

curl https://services.bikeep.com/device/v1/locations/LOCATION_ID/devices \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response (abbreviated):

{
  "data": [
    {
      "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
      "type": "LOCKER",
      "alias": "1",
      "state": {
        "value": "UNLOCKED",
        "changed_at": "2025-12-15T10:30:00Z"
      },
      "hardware_state": "NORMAL",
      "heartbeat_health": "HEALTHY"
    }
  ]
}

Find a device with state.value: "UNLOCKED" — that one is available. Note its id.

Device types vary by location: Locker locations return LOCKER devices, bike dock locations return BIKE_DOCK, and bike houses return a mix of GUARD, BIKE_HOUSE_DOOR, and interior devices. All support the same command pattern shown below.

Tip: The response includes heartbeat_health for backward compatibility, but prefer heartbeat_v2.health for new integrations — it adds a LONG_DEAD value for devices offline 2+ hours. See Device Types — Common Properties.

4. Send Your First Command

Lock a device:

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

Response:

{
  "id": "cmd-1234-5678-abcd",
  "name": "lock",
  "state": { "value": "SENT" }
}

The command has been dispatched to the device. It will travel to the IoT hardware and execute.

5. Check the Result

Poll the device to confirm the state changed:

curl https://services.bikeep.com/device/v1/devices/DEVICE_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The state.value should now be LOCKED (or LOCKING if the command is still in transit).

What’s Next?

You’ve authenticated, discovered devices, and sent a command. Here’s where to go from here: