Access Control API (v1)

The Access Control API connects door hardware to a studio that runs on EYalla. A card reader, turnstile controller or face terminal asks whether a member may come in, and EYalla answers granted or denied. Between scans, your system can read the studio's member list, for example to enrol faces or cards on a terminal.

It is available to studios that have the Access Control add-on switched on.

This is not the Merchant API. Requests go to the studio's own web address, not to api.eyalla.net, and they authenticate with an X-API-Key and X-API-Secret pair, not a Bearer token. Keys from one API never work on the other.

What the studio sends you

The studio creates your credentials in its EYalla admin under Bookings → Access API keys. There it can issue a key, change its secret, revoke it or delete it, and every scan you send appears in its access logs. Ask for one key per integration, so the studio can switch one vendor off without affecting another.

How it works

1. Scan. The member shows their wallet card, taps an access card, or is recognised by a face terminal.
2. Ask. Your device sends the code it read to POST /access/verify.
3. Decide. EYalla checks the account and the membership's dates and pauses, then records the scan in the studio's access log.
4. Act. Open the door only when status is granted. Keep it shut for anything else.

Authentication

Send every request over HTTPS with both credential headers. The key says who you are; the secret proves it. Send and accept JSON.

X-API-Key: ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-API-Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json
Content-Type: application/json

• Keep the secret on a server or controller where it can be changed. Do not build it into device firmware that cannot be updated.
• If the studio changes the secret, the old one stops working at once. Ask for the new one.
• A key the studio has revoked, or one past its expiry date, is refused with 403 key_inactive.
• The secret is checked before anything else about the key is revealed. A wrong secret and an unknown key give the same answer.

Permissions

A key that lacks the permission for a call is refused with 403 missing_scope, and the message names the permission it needs. A door reader that only checks entries needs only access.verify.

Checking a member at the door

POST /access/verify

Send one request for each scan. Once a request has passed authentication, the studio's add-on is on and the body is valid, the answer is always HTTP 200, and the decision is in the body.

Request

{
  "credential_type": "wallet",
  "credential_id": "Hq3Tz8kLmP0aWc5RuY2vNd7XbE4sJf1GtK9oQiA6",
  "action": "entry",
  "device_id": "front-door-01"
}

What each credential is

The QR on the studio app's membership page does not open the door. That page shows a short-lived QR code for front-desk check-in, and this API refuses it. At the door, members use their wallet card (Apple Wallet, Google Wallet or the web card), and its barcode is sent as wallet.

Entry and exit

• entry asks for a decision. Denied scans are recorded too.
• exit is never refused: the answer is always granted, and the scan is recorded as an exit. If the code matches no member, data.user is null.

Response

Granted:

{
  "success": true,
  "status": "granted",
  "message": "Access granted.",
  "data": {
    "log_id": 5120,
    "user": {
      "uuid": "9b2f6c1e-3d4a-4f8e-a1b2-7c9d0e1f2a3b",
      "full_name": "Mona Al-Ali",
      "membership_status": "active"
    },
    "has_booking_today": true,
    "timestamp": "2026-10-08T07:02:11+03:00"
  }
}

Denied, a known member:

{
  "success": false,
  "status": "denied",
  "message": "Membership is frozen.",
  "data": {
    "log_id": 5121,
    "user": {
      "uuid": "4e8a2d70-91c5-4b3f-8e6d-0a1b2c3d4e5f",
      "full_name": "Yousef Hamad",
      "membership_status": "frozen"
    },
    "has_booking_today": false,
    "timestamp": "2026-10-08T07:03:40+03:00"
  }
}

Denied, a code that matches no member:

{
  "success": false,
  "status": "denied",
  "message": "Invalid access credential.",
  "data": {
    "log_id": 5122,
    "user": null,
    "has_booking_today": null,
    "timestamp": "2026-10-08T07:04:02+03:00"
  }
}

Why a scan is denied

In a verify answer, membership_status is the status recorded on the member's latest membership. It can still read active on a denial when that membership's end date has passed. Decide on status alone. The member list reports the door's own view.

Logging, time-outs and retries

• Every call, granted or denied, is written to the studio's access log with your device_id and your IP address. Two identical scans make two entries; nothing is merged.
• Do not resend a scan that received an answer.
• If no answer arrives (time-out or network fault), keep the door shut and let the member scan again. A request time-out of 3 to 5 seconds suits a door. Open on failure only if the studio asks for that in writing.

An invalid request

A body that fails validation gets HTTP 422 with the field-by-field reasons. Send Accept: application/json so the answer is JSON.

{
  "message": "The selected credential type is invalid.",
  "errors": {
    "credential_type": ["The selected credential type is invalid."]
  }
}

The member list

GET /members

Lists the studio's members: everyone who holds, or has held, a membership there. Shop-only customers and removed accounts are not listed. The most recently changed members come first.

Request:

GET /api/v1/external/members?status=active&per_page=100&page=1

Response:

{
  "data": [
    {
      "uuid": "9b2f6c1e-3d4a-4f8e-a1b2-7c9d0e1f2a3b",
      "access_card_id": "0004512890",
      "name": "Mona Al-Ali",
      "membership_status": "active",
      "updated_at": "2026-10-07T18:22:05+03:00"
    }
  ],
  "meta": { "current_page": 1, "last_page": 3, "per_page": 100, "total": 241 }
}

One member

GET /members/{uuid}

Returns the same fields for one member, plus email and is_active (whether the studio has the account switched on). A uuid that is not on the member list returns HTTP 404:

{ "success": false, "message": "Member not found." }

Paging

Read pages in order from 1 to meta.last_page. A full pass over 250 members takes three requests at 100 per page.

Membership status

Keeping your copy up to date

• Re-read the whole list on a schedule. A membership can start, end or be paused without updated_at changing, so comparing updated_at alone misses those changes. Every 15 minutes during opening hours suits most doors and costs only a few requests.
• Match members by uuid. The list can change while you read it, so a member may appear on two pages, or move to a page you have already read. Remove a member from your copy only after a complete pass in which they did not appear.
• Ask at the door whenever you can. A copy is only as fresh as your last pass. If your device decides from its copy while it is offline, it can let in someone whose membership ended after that pass. Whenever the device is online, the verify call is the answer.

Limits

Hourly limit per key

• Each key may make a set number of requests per hour. The default is 1,000; the studio can set any figure from 10 to 100,000.
• Every device that uses the same key shares the same allowance.
• The hour starts with the key's first request and runs for 60 minutes.
• Ask the studio for a limit above your busiest hour of scans plus your sync requests. For example, 400 scans and four 3-page syncs need about 412 requests.
• The limit is set when the key is made. To change it, the studio issues a new key, which comes with a new secret.

Every response that passes authentication carries these headers:

Over the limit, the answer is HTTP 429 with a Retry-After header in seconds:

{
  "success": false,
  "error": "rate_limited",
  "message": "API rate limit exceeded. Try again later.",
  "retry_after": 3600
}

retry_after is always the full hour. The limit may lift sooner, and a request after the hour ends is accepted.

Flood guard

More than 600 requests in one minute from one IP address are refused with HTTP 429 and Retry-After: 60, before the key is checked. No normal door comes close to this.

Errors

Errors use one shape. Act on the HTTP status and error; the message is for people.

{
  "success": false,
  "error": "key_inactive",
  "message": "This API key is inactive or expired."
}

Examples

Replace <studio address>, the key and the secret with the values the studio sent you.

An entry with a wallet card:

curl -X POST "https://<studio address>/api/v1/external/access/verify" \
  -H "X-API-Key: ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"credential_type":"wallet","credential_id":"<code from the barcode>","action":"entry","device_id":"front-door-01"}'

An exit with an access card, naming the reader in a header:

curl -X POST "https://<studio address>/api/v1/external/access/verify" \
  -H "X-API-Key: ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Device-ID: exit-gate-02" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"credential_type":"card","credential_id":"0004512890","action":"exit"}'

The members the door lets in now, 100 at a time:

curl "https://<studio address>/api/v1/external/members?status=active&per_page=100&page=1" \
  -H "X-API-Key: ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

One member:

curl "https://<studio address>/api/v1/external/members/<uuid>" \
  -H "X-API-Key: ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

A door's decision, in outline:

// Called for every scan at an entry reader.
response = POST /access/verify { credential_type, credential_id, action: "entry", device_id }
                with a 3 to 5 second time-out

if no response, or HTTP status is not 200:
    keep the door shut          // show "please try again" or call staff
else if response.status == "granted":
    open the door
else:
    keep the door shut          // response.message may be shown to the member

Security and personal data

• Use HTTPS only. Never put the key or the secret in a web address, a log file or a support ticket.
• If a secret may have leaked, tell the studio. It can change the secret in seconds, and the old one stops working at once.
• The member list is personal data: names, card numbers and, for single reads, e-mail addresses. Keep only what your device needs, protect it like any personal record, and delete it when the integration ends or the studio asks.
• Do not treat a wallet code as a permanent identity. The studio can revoke or reissue a card, and its code changes when it does. Key your records on the member's uuid.

Go-live checklist

• You have the base address, the key and the secret, and the secret came separately from the key.
• Each reader sends its own device_id.
• Your scanners read both QR codes and Code 128 barcodes.
• The card-number format is agreed with the studio's front desk, and one test card paired at the desk is granted at your reader.
• Tested with the studio: a member with an active membership is granted; a frozen and an expired member are denied; an unknown code is denied; an exit is recorded in the studio's access log.
• The door opens only when status is granted, and stays shut after a time-out or an error.
• The hourly limit covers your busiest hour of scans plus syncs.
• If you keep a copy of the member list, it re-reads the whole list on a schedule.

Questions about a studio's set-up, keys or members go to that studio. Questions about this API go to developers@eyalla.com.