Skip to main content
API docs by Redocly

Entrosity Edge Portal API (0.1.0)

Download OpenAPI specification:Download

Entrosity Edge portal REST API: physical access control with TRAcK ACCESS controllers, RFID readers and cards. This file is the source of truth for the backend server interfaces (oapi-codegen), request validation, and the frontend types (openapi-typescript). Run make gen after editing.

Authentication: Authorization: Bearer <product token>: users sign in on Entrosity Hub, which issues five-minute product tokens for Edge (POST /api/platform/v1/auth/product-token {"product":"edge"}, with the Hub's session cookie). Users, tenants (the Hub's organizations) and roles are managed on the Hub; Edge keeps a copy.

Every route's access rule (public, authenticated, global admin, tenant permission) is declared in internal/http/portal/access.go and enforced before the handler runs.

system

Liveness probe

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

auth

Short-lived token for a tenant live stream (EventSource)

Returns a token valid for 60 seconds that opens GET /tenants/{tenantID}/stream?sse_token= for the given tenant and the caller's session. Access to the tenant is checked when the stream opens. Keeps the access token out of URLs.

Authorizations:
bearerAuth
Request Body schema: application/json
required
tenant_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "expires_in": 0
}

The signed-in user with their tenants and roles

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "string",
  • "display_name": "string",
  • "status": "active",
  • "is_global_admin": true,
  • "memberships": [
    ],
  • "created_at": "2019-08-24T14:15:22Z"
}

admin

Cross-tenant counters

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "tenants_total": 0,
  • "tenants_active": 0,
  • "global_admins": 0,
  • "tenant_users": 0
}

List tenants

Authorizations:
bearerAuth
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
status
string (TenantStatus)
Enum: "active" "suspended"

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Global admins (the platform admins of Entrosity Hub)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Cross-tenant audit log

Authorizations:
bearerAuth
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
tenant_id
string <uuid>
actor_user_id
string <uuid>
action
string <= 100 characters
resource_type
string <= 100 characters
from
string <date-time>
to
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Edge connector releases stored for self-update

Releases are published by CI with POST /api/v1/admin/connector-releases?version=&channel=&notes= (Authorization: Bearer <EDGE_RELEASE_TOKEN>, the MSI as an application/octet-stream body of at most 64 MiB). That endpoint is not part of this portal contract; see docs/operations/edge.md (Connector releases).

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "signing_enabled": true,
  • "public_key": "string"
}

tenant

Tenant profile

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "status": "active",
  • "settings": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change the tenant's settings (the name is the Hub's)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
object (TenantSettings)
default_timezone
string <= 64 characters

IANA time zone of the schedules of controllers without a site (default UTC).

object (TenantRetention)

Overrides of the server's retention windows (sent as a whole).

Responses

Request samples

Content type
application/json
{
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "slug": "string",
  • "status": "active",
  • "settings": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Counters, controller health and today's traffic

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "connectors_total": 0,
  • "connectors_online": 0,
  • "controllers_total": 0,
  • "controllers_online": 0,
  • "controllers_pending": 0,
  • "controllers_failed": 0,
  • "doors_total": 0,
  • "cardholders_active": 0,
  • "cards_active": 0,
  • "groups_total": 0,
  • "sites_total": 0,
  • "events_today": 0,
  • "granted_today": 0,
  • "denied_today": 0,
  • "hourly": [
    ]
}

Tenant members and their roles (managed on Entrosity Hub)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "users": [
    ]
}

Sites of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 200 ] characters
description
string <= 2000 characters
timezone
string [ 1 .. 64 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
siteID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update a site (a new time zone resyncs its controllers)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
siteID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
description
string <= 2000 characters
timezone
string [ 1 .. 64 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",
  • "name": "string",
  • "description": "string",
  • "timezone": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a site (its connectors and controllers stay, without a site)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
siteID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Audit log of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
actor_user_id
string <uuid>
action
string <= 100 characters
resource_type
string <= 100 characters
from
string <date-time>
to
string <date-time>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

connectors

Connector enrollment tokens of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a connector enrollment token (the secret is returned once)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
label
string <= 200 characters
site_id
string <uuid>
expires_at
string <date-time>
max_uses
integer [ 1 .. 100000 ]

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "max_uses": 1
}

Response samples

Content type
application/json
{
  • "token": {
    },
  • "secret": "string",
  • "install_command": "string",
  • "cli_command": "string",
  • "download_url": "string"
}

Revoke an enrollment token

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
tokenID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Delete an enrollment token permanently (global admins; requires the password)

Global admins confirm with their own password: they send step_up_token, which Entrosity Hub issues for the password (POST /api/platform/v1/auth/step-up, product edge).

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
tokenID
required
string <uuid>
Request Body schema: application/json
required
step_up_token
required
string [ 1 .. 4096 ] characters

Responses

Request samples

Content type
application/json
{
  • "step_up_token": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Edge connectors of the tenant

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get a connector

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "name": "string",
  • "hostname": "string",
  • "domain": "string",
  • "version": "string",
  • "capabilities": [
    ],
  • "status": "online",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "controller_count": 0,
  • "update_channel": "stable",
  • "update_version": "string",
  • "update_offered_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Rename a connector or move it to a site

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>
Request Body schema: application/json
required
name
string <= 200 characters
site_id
string <uuid>
clear_site
boolean

Remove the connector from its site.

update_channel
string (UpdateChannel)
Enum: "stable" "beta"

Which releases the connector updates to (beta also receives stable releases).

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "clear_site": true,
  • "update_channel": "stable"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "name": "string",
  • "hostname": "string",
  • "domain": "string",
  • "version": "string",
  • "capabilities": [
    ],
  • "status": "online",
  • "last_seen_at": "2019-08-24T14:15:22Z",
  • "controller_count": 0,
  • "update_channel": "stable",
  • "update_version": "string",
  • "update_offered_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z"
}

Remove a connector (409 connector_has_controllers while it drives controllers)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Look for controllers on the connector's network

Creates an edge.discover job; poll GET /tenants/{tenantID}/jobs/{jobID} (or watch job.update) for its result, a DiscoverResult. 409 connector_offline when the connector is not connected.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
connectorID
required
string <uuid>
Request Body schema: application/json
required
driver
required
string (Driver)
Enum: "simulator" "trackbase002"

simulator is a software controller for trials and tests.

transport
string (Transport)
Enum: "tcp" "rs485"
addresses
Array of strings <= 256 items [ items <= 255 characters ]

host:port addresses to probe (TrackBase); empty for the simulator.

Responses

Request samples

Content type
application/json
{
  • "driver": "simulator",
  • "transport": "tcp",
  • "addresses": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "controller_id": "d9594ac9-2986-4a07-9d98-c9104109e8c5",
  • "type": "string",
  • "status": "created",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "error_code": "string",
  • "error": "string",
  • "result": { }
}

A connector job (discovery, test, door opening, configuration)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
jobID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "controller_id": "d9594ac9-2986-4a07-9d98-c9104109e8c5",
  • "type": "string",
  • "status": "created",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "error_code": "string",
  • "error": "string",
  • "result": { }
}

controllers

Access controllers

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
connector_id
string <uuid>
site_id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "capacity": 0
}

Add a controller (its doors and readers are created from the door mode)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
connector_id
required
string <uuid>
site_id
string <uuid>
name
required
string [ 1 .. 200 ] characters
driver
required
string (Driver)
Enum: "simulator" "trackbase002"

simulator is a software controller for trials and tests.

transport
string (Transport)
Enum: "tcp" "rs485"
address
required
string [ 1 .. 255 ] characters

host:port (tcp)

unit_id
integer [ 0 .. 31 ]

RS-485 bus address (1-31).

door_mode
required
string (DoorMode)
Enum: "one_bidirectional" "two_unidirectional"
model
string <= 100 characters
serial
string <= 100 characters
firmware
string <= 100 characters
pin
integer <int64> (ControllerPIN) [ 1 .. 4294967294 ]

The controller's PIN (TrackBase002 only; 422 for other drivers). Write-only.

Responses

Request samples

Content type
application/json
{
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "name": "string",
  • "driver": "simulator",
  • "transport": "tcp",
  • "address": "string",
  • "unit_id": 0,
  • "door_mode": "one_bidirectional",
  • "model": "string",
  • "serial": "string",
  • "firmware": "string",
  • "pin": 1
}

Response samples

Content type
application/json
{
  • "controller": {
    },
  • "doors": [
    ],
  • "readers": [
    ]
}

A controller with its doors and readers

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
controllerID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "controller": {
    },
  • "doors": [
    ],
  • "readers": [
    ]
}

Rename, move to a site, change the bus address, PIN or doors layout, enable or disable

Only the fields sent change. A new door_mode rebuilds the doors and readers as creating the controller with that mode does: door 1 (with its id, name and timing) always stays, door 2 is added or removed, and the readers are wired to the new layout. 409 door_in_use (naming the access groups) when door 2 would be removed while access groups use it.

enabled false disables the controller (open configuration jobs are cancelled, the connector gets edge.controller.remove); enabled true enables it and forces a resync. A disabled controller can still be edited (nothing is sent until it is enabled); opening its doors, testing it and resyncing it are refused with 409 controller_disabled.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
controllerID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
site_id
string <uuid>
clear_site
boolean

Remove the controller from its site.

transport
string (Transport)
Enum: "tcp" "rs485"
address
string [ 1 .. 255 ] characters
unit_id
integer [ 0 .. 31 ]
pin
integer <int64> (ControllerPIN) [ 1 .. 4294967294 ]

The controller's PIN (TrackBase002 only; 422 for other drivers). Write-only.

clear_pin
boolean

Remove the controller's PIN (not together with pin).

door_mode
string (DoorMode)
Enum: "one_bidirectional" "two_unidirectional"
enabled
boolean

false disables the controller: its pending configurations are cancelled and its connector is told to stop driving it (edge.controller.remove). true enables it again and forces a resync.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "clear_site": true,
  • "transport": "tcp",
  • "address": "string",
  • "unit_id": 0,
  • "pin": 1,
  • "clear_pin": true,
  • "door_mode": "one_bidirectional",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "controller": {
    },
  • "doors": [
    ],
  • "readers": [
    ]
}

Remove a controller with its doors and readers

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
controllerID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Send the controller's configuration again

409 controller_disabled when the controller is disabled.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
controllerID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Ask the connector to reach the controller (result is a ControllerInfo)

409 controller_disabled when the controller is disabled.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
controllerID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "controller_id": "d9594ac9-2986-4a07-9d98-c9104109e8c5",
  • "type": "string",
  • "status": "created",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "error_code": "string",
  • "error": "string",
  • "result": { }
}

Recent jobs of the controller

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
controllerID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Change which door a reader serves, its direction, name, or disable it

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
readerID
required
string <uuid>
Request Body schema: application/json
required
door_id
string <uuid>
direction
string (Direction)
Enum: "in" "out"
name
string <= 200 characters
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "door_id": "64c2abcc-dbb1-4339-b149-a6e1d873bae5",
  • "direction": "in",
  • "name": "string",
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "controller_id": "d9594ac9-2986-4a07-9d98-c9104109e8c5",
  • "door_id": "64c2abcc-dbb1-4339-b149-a6e1d873bae5",
  • "channel": "wiegand1",
  • "direction": "in",
  • "name": "string",
  • "enabled": true
}

doors

Doors of every controller

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
site_id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Rename a door or change its lock relay and timing

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
doorID
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
lock_relay
integer [ 1 .. 4 ]
open_pulse_ms
integer [ 100 .. 60000 ]
held_open_seconds
integer [ 0 .. 3600 ]

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "lock_relay": 1,
  • "open_pulse_ms": 100,
  • "held_open_seconds": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "controller_id": "d9594ac9-2986-4a07-9d98-c9104109e8c5",
  • "controller_name": "string",
  • "controller_status": "unknown",
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "site_name": "string",
  • "index": 0,
  • "name": "string",
  • "lock_relay": 0,
  • "open_pulse_ms": 0,
  • "held_open_seconds": 0,
  • "is_open": true,
  • "is_locked": true,
  • "state_at": "2019-08-24T14:15:22Z"
}

Open a door remotely (for its pulse time)

409 connector_offline when the controller's connector is not connected; 409 controller_disabled when the door's controller is disabled.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
doorID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "connector_id": "9389ba6f-3696-4571-84d4-34d588c4b109",
  • "controller_id": "d9594ac9-2986-4a07-9d98-c9104109e8c5",
  • "type": "string",
  • "status": "created",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "sent_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "progress_pct": 0,
  • "progress_message": "string",
  • "error_code": "string",
  • "error": "string",
  • "result": { }
}

people

Cardholders

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
status
string (CardholderStatus)
Enum: "active" "suspended"
group_id
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Add a cardholder

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
first_name
required
string [ 1 .. 100 ] characters
last_name
string <= 100 characters
email
string <= 254 characters
phone
string <= 50 characters
department
string <= 100 characters
external_ref
string <= 100 characters
notes
string <= 2000 characters
status
string (CardholderStatus)
Enum: "active" "suspended"
valid_from
string or null <date-time>
valid_to
string or null <date-time>
group_ids
Array of strings <uuid> <= 200 items [ items <uuid > ]

Replaces the cardholder's access groups when present.

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "phone": "string",
  • "department": "string",
  • "external_ref": "string",
  • "notes": "string",
  • "status": "active",
  • "valid_from": "2019-08-24T14:15:22Z",
  • "valid_to": "2019-08-24T14:15:22Z",
  • "group_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "cardholder": {
    },
  • "cards": [
    ],
  • "groups": [
    ]
}

A cardholder with their cards and groups

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
cardholderID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "cardholder": {
    },
  • "cards": [
    ],
  • "groups": [
    ]
}

Replace a cardholder's details (and, when given, groups)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
cardholderID
required
string <uuid>
Request Body schema: application/json
required
first_name
required
string [ 1 .. 100 ] characters
last_name
string <= 100 characters
email
string <= 254 characters
phone
string <= 50 characters
department
string <= 100 characters
external_ref
string <= 100 characters
notes
string <= 2000 characters
status
string (CardholderStatus)
Enum: "active" "suspended"
valid_from
string or null <date-time>
valid_to
string or null <date-time>
group_ids
Array of strings <uuid> <= 200 items [ items <uuid > ]

Replaces the cardholder's access groups when present.

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "email": "string",
  • "phone": "string",
  • "department": "string",
  • "external_ref": "string",
  • "notes": "string",
  • "status": "active",
  • "valid_from": "2019-08-24T14:15:22Z",
  • "valid_to": "2019-08-24T14:15:22Z",
  • "group_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "cardholder": {
    },
  • "cards": [
    ],
  • "groups": [
    ]
}

Remove a cardholder (their cards return to the pool)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
cardholderID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Cards (RFID and iButton credentials)

q matches the facility:number form, the card number, the 10-digit number printed on Wiegand 26 cards ((facility_code << 16) | card_number, with or without its leading zeros), the iButton id, the label and the cardholder's name.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
page
integer [ 1 .. 100000 ]
Default: 1
page_size
integer [ 1 .. 200 ]
Default: 50
q
string <= 200 characters
cardholder_id
string <uuid>
unassigned
boolean

Only cards without a cardholder (the pool).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Register a card (409 card_already_registered for a duplicate number)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
kind
required
string (CredentialKind)
Enum: "wiegand26" "ibutton"
facility_code
integer [ 0 .. 255 ]
card_number
integer [ 0 .. 65535 ]
ibutton_id
string^[0-9A-Fa-f]{2,16}$
cardholder_id
string <uuid>
status
string (CardStatus)
Enum: "active" "suspended" "lost"
label
string <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "kind": "wiegand26",
  • "facility_code": 0,
  • "card_number": 0,
  • "ibutton_id": "string",
  • "cardholder_id": "b41a5553-f9d1-4565-a52e-86ef53ff44f9",
  • "status": "active",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "cardholder_id": "b41a5553-f9d1-4565-a52e-86ef53ff44f9",
  • "cardholder_name": "string",
  • "kind": "wiegand26",
  • "facility_code": 0,
  • "card_number": 0,
  • "ibutton_id": "string",
  • "display": "string",
  • "status": "active",
  • "label": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Assign, unassign, block (suspended, lost) or reactivate a card

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
cardID
required
string <uuid>
Request Body schema: application/json
required
cardholder_id
string <uuid>

Assign the card to this cardholder.

unassign
boolean

Return the card to the pool of unassigned cards.

status
string (CardStatus)
Enum: "active" "suspended" "lost"
label
string <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "cardholder_id": "b41a5553-f9d1-4565-a52e-86ef53ff44f9",
  • "unassign": true,
  • "status": "active",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "cardholder_id": "b41a5553-f9d1-4565-a52e-86ef53ff44f9",
  • "cardholder_name": "string",
  • "kind": "wiegand26",
  • "facility_code": 0,
  • "card_number": 0,
  • "ibutton_id": "string",
  • "display": "string",
  • "status": "active",
  • "label": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Delete a card

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
cardID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

policy

Weekly time schedules

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a schedule

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters
description
string <= 500 characters
required
Array of objects (Interval) <= 64 items

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "intervals": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "intervals": [
    ],
  • "usage_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

A schedule

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
scheduleID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "intervals": [
    ],
  • "usage_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Replace a schedule (controllers using it are resynced)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
scheduleID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters
description
string <= 500 characters
required
Array of objects (Interval) <= 64 items

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "intervals": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "description": "string",
  • "intervals": [
    ],
  • "usage_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a schedule (409 schedule_in_use while access groups use it)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
scheduleID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Holidays

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
from
string <date>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add a holiday (every controller is resynced)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
date
required
string <date>
name
required
string [ 1 .. 100 ] characters

Responses

Request samples

Content type
application/json
{
  • "date": "2019-08-24",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "date": "2019-08-24",
  • "name": "string"
}

Delete a holiday

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
holidayID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Access groups

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create an access group

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters
description
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "group": {
    },
  • "doors": [
    ],
  • "members": [
    ]
}

An access group with its doors and members

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
groupID
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "group": {
    },
  • "doors": [
    ],
  • "members": [
    ]
}

Rename an access group

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
groupID
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters
description
string <= 500 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "group": {
    },
  • "doors": [
    ],
  • "members": [
    ]
}

Delete an access group

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
groupID
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

Replace the group's doors, each with the schedule it is open for members

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
groupID
required
string <uuid>
Request Body schema: application/json
required
required
Array of objects <= 500 items
Array (<= 500 items)
door_id
required
string <uuid>
schedule_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "doors": [
    ]
}

Response samples

Content type
application/json
{
  • "group": {
    },
  • "doors": [
    ],
  • "members": [
    ]
}

Add and remove members

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
groupID
required
string <uuid>
Request Body schema: application/json
required
add
Array of strings <uuid> <= 1000 items [ items <uuid > ]
remove
Array of strings <uuid> <= 1000 items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "add": [
    ],
  • "remove": [
    ]
}

Response samples

Content type
application/json
{
  • "group": {
    },
  • "doors": [
    ],
  • "members": [
    ]
}

events

Live updates (server-sent events)

text/event-stream of the tenant's live updates: access.events (new access log entries, an array), controller.status, controller.sync, door.state, connector.status and job.update. Authenticate with a bearer token or, for EventSource, ?sse_token= from POST /auth/sse-token.

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
sse_token
string <= 4096 characters

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "code": "string",
  • "instance": "string",
  • "request_id": "string",
  • "fields": {
    }
}

The access event log, newest first (keyset pagination)

Authorizations:
bearerAuth
path Parameters
tenantID
required
string <uuid>
query Parameters
before_at
string <date-time>

Cursor from the previous page (next_before_at).

before_id
string <uuid>
from
string <date-time>
to
string <date-time>
door_id
string <uuid>
controller_id
string <uuid>
cardholder_id
string <uuid>
type
Array of strings <= 20 items [ items <= 64 characters ]

Event types (repeat the parameter for several).

limit
integer [ 1 .. 500 ]
Default: 100

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "has_more": true,
  • "next_before_at": "2019-08-24T14:15:22Z",
  • "next_before_id": "0ce7fc60-5733-4ae4-967b-4beb905a3fd7"
}