Quick-Start

this guide walks you through setting up your first be-in integration in five minutes.

1. obtain partner api key

contact be-in support – you will receive a uuid string such as:

cb2e8c89-b2b4-4d3b-8d7b-97f4753c8f8e

2. create webhook endpoint

first, set up an https endpoint that will receive entry notifications:

POST /v1/webhooks/endpoints
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "url": "https://example.com/bein-webhooks",
  "events": ["entry.recorded"]
}

response 201:

{
  "id": "7ad9…",
  "secret": "98ad6e3b…",
  "url": "https://example.com/bein-webhooks",
  "events": ["entry.recorded"]
}

keep the secret safe – you'll need it to verify webhook signatures.

3. check available pods

see which pods your partner account can generate qr codes for:

curl -H "Authorization: Bearer <api-key>" \
  https://api-v3.be-in.app/v1/pods

[
  {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Main Entrance",
    "location": "Gym Alpha"
  }
]

4. generate a qr code

request a qr code for one of your allowed pods:

curl -X POST https://api-v3.be-in.app/v1/qr-code \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "pod_id": "11111111-1111-1111-1111-111111111111",
    "validity_minutes": 5,
    "metadata": {"external_user_id": "abc-123", "purpose": "guest-pass"}
  }' \
  --output qr.png

successful response:

200 OK
Content-Type: image/png
X-Request-Id: bein_8N1r6W2XK

<PNG bytes saved to qr.png>

5. test the webhook

when someone scans the qr code at the pod, your webhook endpoint will receive:

{
  "id": "fe29…",
  "type": "entry.recorded",
  "created_at": "2024-05-31T12:34:56.789Z",
  "data": {
    "request_id": "bein_8N1r6W2XK",
    "pod_id": "11111111-1111-1111-1111-111111111111",
    "scanned_at": "2024-05-31T12:35:02.789Z",
    "metadata": {
      "external_user_id": "abc-123",
      "purpose": "guest-pass",
    },
  },
}

your endpoint should:

verify the hmac signature (see security)
respond with 200 quickly (< 3 seconds)
process the entry event (grant access, log the visit, etc.)

6. next steps

handle real events in production
monitor failed deliveries in the dashboard
read event catalogue for full payload details
check api reference for advanced features