API section

Access control and turnstiles

The Access control and turnstiles module: open a gate (Modbus relay, USB relay, HTTP controller), passes after a sale (ticket codes with an entry count and expiry), code checks against the agent list or your server, the passage log. Codes from scanners and cards from readers linked to a gate are checked automatically; event access.passage. Needs the access-control module in the key (except the emulator).

GET	`/api/v1/access/passes`	Passes
POST	`/api/v1/access/passes`	Add passes
DELETE	`/api/v1/access/passes`	Delete passes
POST	`/api/v1/access/gates/{number}/open`	Open a gate
POST	`/api/v1/access/check`	Check code and open
GET	`/api/v1/access/gates`	Gates
GET	`/api/v1/access/events`	Passage log
DELETE	`/api/v1/access/passes/{code}`	Delete a pass

Passes#

GET/api/v1/access/passes

Most recently added; code for a single pass

Parameters

Name	In	Type	Description
`code`	query	string
`limit`	query	integer int32

Response 200 application/json

Fields · PassList

passesarray of Pass
10 fields · Pass
- codestring
- labelstring
- usesinteger int32
- usedinteger int32
- validFromstring date-time
- validUntilstring date-time
- gatesarray of integer int32
- orderstring
- createdAtstring date-time
- lastUsedAtstring date-time

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/access/passes'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/access/passes' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Add passes#

POST/api/v1/access/passes

After a sale, the ticket codes: {"passes":[{"code":"…","label":"Row 5 seat 12","uses":1, "validUntil":"2026-11-05T21:00:00Z","gates":[1,2],"order":"A-1001"}]}. The same code replaces the old one. Up to 10,000 at once

Request body application/json required

Fields · PassList

passesarray of Pass
10 fields · Pass
- codestring
- labelstring
- usesinteger int32
- usedinteger int32
- validFromstring date-time
- validUntilstring date-time
- gatesarray of integer int32
- orderstring
- createdAtstring date-time
- lastUsedAtstring date-time

JSON

{
  "passes": [
    {
      "code": "string",
      "label": "string",
      "uses": 1,
      "used": 1,
      "validFrom": "2026-11-01T19:00:00+03:00",
      "validUntil": "2026-11-01T19:00:00+03:00",
      "gates": [
        1
      ],
      "order": "string",
      "createdAt": "2026-11-01T19:00:00+03:00",
      "lastUsedAt": "2026-11-01T19:00:00+03:00"
    }
  ]
}

Response 200 application/json

Fields · Saved

savedinteger int32
totalinteger int32

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/access/passes' \
  -H 'Content-Type: application/json' \
  --data '{"passes":[{"code":"string","label":"string","uses":1,"used":1,"validFrom":"2026-11-01T19:00:00+03:00","validUntil":"2026-11-01T19:00:00+03:00","gates":[1],"order":"string","createdAt":"2026-11-01T19:00:00+03:00","lastUsedAt":"2026-11-01T19:00:00+03:00"}]}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/access/passes' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Content-Type: application/json' \
  --data '{"passes":[{"code":"string","label":"string","uses":1,"used":1,"validFrom":"2026-11-01T19:00:00+03:00","validUntil":"2026-11-01T19:00:00+03:00","gates":[1],"order":"string","createdAt":"2026-11-01T19:00:00+03:00","lastUsedAt":"2026-11-01T19:00:00+03:00"}]}'

Delete passes#

DELETE/api/v1/access/passes

order deletes all passes of an order (order refund); without it, all

Parameters

Name	In	Type	Description
`order`	query	string

Response 200 application/json

Fields · Deleted

deletedinteger int32

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X DELETE 'http://localhost:7790/api/v1/access/passes'

curl

curl -X DELETE 'https://cloud.hw-connector.ru/agent/api/v1/access/passes' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Open a gate#

POST/api/v1/access/gates/{number}/open

Without a code check: open after a sale, a guard button. The reply is a log entry; event access.passage. Without the module key — 402 LICENSE_REQUIRED (except the emulator)

Parameters

Name	In	Type	Description
`number`required	path	integer int32

Request body application/json

Fields · OpenRequest

directionstring
pulseMsinteger int32
reasonstring

JSON

{
  "direction": "string",
  "pulseMs": 1,
  "reason": "string"
}

Response 200 application/json

Fields · Passage

atstring date-time
gateinteger int32
gateNamestring
directionstring
codestring
grantedboolean
reasonstring
messagestring
sourcestring
labelstring
orderstring
remaininginteger int32

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/access/gates/1/open' \
  -H 'Content-Type: application/json' \
  --data '{"direction":"string","pulseMs":1,"reason":"string"}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/access/gates/1/open' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Content-Type: application/json' \
  --data '{"direction":"string","pulseMs":1,"reason":"string"}'

Check code and open#

POST/api/v1/access/check

A code your app read itself (kiosk camera, its own scanner). Checked like the gate's readers: against the agent's list or on your server. granted: false and reason say why not (UNKNOWN, USED, EXPIRED…)

Request body application/json required

Fields · CheckRequest

typestring
values: SELL SELL_RETURN BUY BUY_RETURN
registerIdinteger int32
codesarray of CodeRequestrequired
from 1
3 fields · CodeRequest
- codestringrequired
  from 1
- priceinteger int64
- fractionstring

JSON

{
  "type": "SELL",
  "registerId": 1,
  "codes": [
    {
      "code": "string",
      "price": 1,
      "fraction": "string"
    }
  ]
}

Response 200 application/json

Fields · Passage

atstring date-time
gateinteger int32
gateNamestring
directionstring
codestring
grantedboolean
reasonstring
messagestring
sourcestring
labelstring
orderstring
remaininginteger int32

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X POST 'http://localhost:7790/api/v1/access/check' \
  -H 'Content-Type: application/json' \
  --data '{"type":"SELL","registerId":1,"codes":[{"code":"string","price":1,"fraction":"string"}]}'

curl

curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/access/check' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42' \
  -H 'Content-Type: application/json' \
  --data '{"type":"SELL","registerId":1,"codes":[{"code":"string","price":1,"fraction":"string"}]}'

Gates#

GET/api/v1/access/gates

Turnstiles, wickets and locks of the workstation with their readers and code check method

Response 200 application/json

Fields · GateList

licensedboolean
passesinteger int32
gatesarray of GateInfo
8 fields · GateInfo
- numberinteger int32
- namestring
- typestring
- activeboolean
- directionsarray of string
- readersarray of string
- checkstring
- infomap → any value

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/access/gates'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/access/gates' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Passage log#

GET/api/v1/access/events

Latest attempts, newest first, up to 1000; cleared when the agent restarts

Parameters

Name	In	Type	Description
`limit`	query	integer int32

Response 200 application/json

Array · Passage

atstring date-time
gateinteger int32
gateNamestring
directionstring
codestring
grantedboolean
reasonstring
messagestring
sourcestring
labelstring
orderstring
remaininginteger int32

Errors — problem+json with a code field, see error codes.

Request example

curl

curl 'http://localhost:7790/api/v1/access/events'

curl

curl 'https://cloud.hw-connector.ru/agent/api/v1/access/events' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'

Delete a pass#

DELETE/api/v1/access/passes/{code}

Ticket refund

Parameters

Name	In	Type	Description
`code`required	path	string

Response 200

No body.

Errors — problem+json with a code field, see error codes.

Request example

curl

curl -X DELETE 'http://localhost:7790/api/v1/access/passes/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11'

curl

curl -X DELETE 'https://cloud.hw-connector.ru/agent/api/v1/access/passes/3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11' \
  -H 'X-Api-Key: hwk_…' \
  -H 'X-Device-Id: 42'