Access Lists

An access list is a Bikeep-managed roster of users who are granted access at one or more locations. Bikeep provisions the access list and gives you its ID; you use the access-control API to add, remove, and inspect its members.

Access lists are not whitelists. Whitelists (allowlists) are RFID card lists managed via the whitelist API. Access lists are a subscription/membership model for user accounts. The two features are independent — see the Glossary for definitions.

Prerequisites

• Operator backend credentials via S2S OAuth2 (client-credentials), authorized to manage the access list. See Authentication.
• The access_list_id for your list, provided by Bikeep.

Access List Types

Bikeep configures an access list as one of three types: paid, closed, or password.

The billing fields payment_period, recurring_payment, and the remove_now removal-timing flag apply only to paid lists and are ignored for closed and password lists. Bikeep sets the type — your integration does not choose it, but must handle field applicability correctly.

API Base URL

All access-control endpoints share this base URL:

https://services.bikeep.com/access-control/v1

All requests require:

Authorization: Bearer <token>
Content-Type: application/json

Operations

List Members

Retrieve all current members of an access list, including any pending phone invites.

curl -X GET \
  "https://services.bikeep.com/access-control/v1/mgmt/access-lists/{access_list_id}/users" \
  -H "Authorization: Bearer <token>"

Response: 200 OK

{
  "uri": "/mgmt/access-lists/al_01HXYZ/users",
  "data": [
    {
      "user_id": "usr_01ABCD",
      "status": "included:active",
      "joined_at": "2026-01-10T09:00:00Z",
      "expires_at": "",
      "payment_period": "month",
      "recurring_payment": true,
      "next_payment_at": "2026-07-10T09:00:00Z",
      "comment": "Annual contract employee",
      "external_id": "ext_emp_4821"
    },
    {
      "user_id": "usr_05EFGH",
      "status": "excluded:expired",
      "joined_at": "2025-11-01T08:30:00Z",
      "expires_at": "2026-05-01T08:30:00Z",
      "payment_period": "month",
      "recurring_payment": false,
      "next_payment_at": "",
      "comment": ""
    },
    {
      "user_id": "",
      "phone_number": "+3725559876",
      "status": "invited",
      "joined_at": "",
      "expires_at": "2026-07-25T00:00:00Z",
      "payment_period": "month",
      "recurring_payment": true,
      "next_payment_at": "",
      "comment": "New hire — pending sign-up",
      "external_id": "ext_emp_4822"
    }
  ]
}

Member Object Fields

Add a Member

Add a user to the access list by Bikeep user ID, or invite someone by phone number.

Provide either user_id or phone_number — not both.

curl -X POST \
  "https://services.bikeep.com/access-control/v1/mgmt/access-lists/{access_list_id}/users" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+3725551234",
    "payment_period": "month",
    "recurring_payment": true,
    "comment": "Q3 seasonal pass",
    "external_id": "ext_emp_4821"
  }'

Response: 204 No Content

Request Body Fields

Remove a Member

Remove a user from the access list, or cancel a pending phone invite.

Provide either user_id or phone_number — not both.

curl -X POST \
  "https://services.bikeep.com/access-control/v1/mgmt/access-lists/{access_list_id}/remove-user" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_01ABCD",
    "remove_now": false
  }'

Response: 204 No Content

Request Body Fields

Member Statuses

The status field uses a namespaced enum. Members with an included:* status currently have access; members with an excluded:* status do not.

Important Notes

• Exactly one of user_id or phone_number must be provided per add or remove request — not both, not neither.
• Authorization is per-list. Your credentials must be granted management access to the specific access_list_id (Bikeep configures this when provisioning the list). A request targeting a list you are not authorized to manage is rejected, even with otherwise-valid credentials.
• Phone invite flow: When you add by phone_number and no Bikeep account exists for that number, the member’s status is invited and their user_id is empty. On the invited person’s first sign-in to Bikeep, they are promoted to a full member automatically.
• Removal timing (remove_now) applies only to paid lists. For closed and password lists, and for any pending invite regardless of list type, removal is always immediate.
• Billing fields (payment_period, recurring_payment) are ignored on closed and password lists. Bikeep sets the list type — include only the fields that apply, or expect them to be silently ignored.
• external_id for correlation: When a third-party system adds members by phone_number, the number is used to match a Bikeep account and is then dropped — it is not stored long term. Supplying external_id at add time attaches your own opaque identifier to the membership so you can correlate your records to Bikeep members. The identifier is returned in list responses and persists through the phone invite → full member promotion (when the invited person first signs in to Bikeep). To remove a member you tracked this way, list the members (GET .../users), find the entry whose external_id matches, and remove it by its user_id.
• Access lists are distinct from whitelists (allowlists). Whitelists manage RFID card access via the whitelist API. Access lists manage user-account memberships via this API. See the Glossary for the full definitions of both features.

Related

• API Reference — Access Lists — full endpoint and field reference
• Authentication — obtaining S2S OAuth2 (service-to-service) operator credentials
• Glossary — definitions for access list, whitelist, allowlist, and related terms