Skip to content

UniFi Access API — Usage Guide ​

Complete guide for integrating with the UniFi Access API using the OpenAPI specification in this repository.

Prerequisites ​

  • UniFi Access v1.9.1 or later (API is not available after upgrading to Identity Enterprise)
  • An API Token created from: UniFi Portal → Access → Settings → General → Advanced → API Token
  • Network access to the UniFi Console on port 12445 (HTTPS)

Quick Start ​

1. Obtain API Token ​

  1. Sign in to UniFi Portal
  2. Select the Console running UniFi Access
  3. Navigate to Access → Settings → General → Advanced
  4. Click Create New under API Token, set name / expiry / permission scopes
  5. Copy the token immediately — it is shown only once

2. Determine Your API Host ​

https://<console-ip>:12445

The server uses a self-signed certificate. Add --insecure (curl) or disable certificate verification in your HTTP client.

3. Make Your First Request ​

bash
# List all users (paginated)
curl -k 'https://192.168.1.1:12445/api/v1/developer/users?page_num=1&page_size=25' \
  -H 'Authorization: Bearer <YOUR_API_TOKEN>' \
  -H 'Accept: application/json'

Authentication ​

All requests require a Bearer token in the Authorization header:

Authorization: Bearer <API_TOKEN>

Tokens are scoped by permission keys (e.g., edit:user, view:user, edit:visitor). Ensure your token has the required scope for each endpoint.

Response Format ​

Every response follows a consistent envelope:

json
{
  "code": "SUCCESS",
  "msg": "success",
  "data": { ... }
}
FieldDescription
code"SUCCESS" or an error code (e.g., CODE_PARAMS_INVALID)
msgHuman-readable message
dataPayload — object, array, or paginated result

Pagination ​

Paginated endpoints accept page_num and page_size query parameters and return:

json
{
  "code": "SUCCESS",
  "data": [ ... ],
  "pagination": {
    "page_num": 1,
    "page_size": 25,
    "total": 142
  }
}

API Categories ​

User Management (29 endpoints) ​

CRUD operations for users and user groups, including credential assignment.

OperationMethodPath
Create userPOST/api/v1/developer/users
Get / Update / Delete userGET / PUT / DELETE/api/v1/developer/users/{id}
Search usersPOST/api/v1/developer/users/search
Assign NFC cardPUT/api/v1/developer/users/{id}/nfc_cards
Assign PIN codePUT/api/v1/developer/users/{id}/pin_codes
Assign access policyPUT/api/v1/developer/users/{id}/access_policies
Upload avatarPOST/api/v1/developer/users/{id}/avatar
CRUD user groupsPOST / GET / PUT / DELETE/api/v1/developer/user_groups[/{id}]
Assign license platesPUT/api/v1/developer/users/{id}/license_plates

Visitor Management (13 endpoints) ​

Manage visitors with time-limited access, NFC, PIN, QR code, and license plate credentials.

OperationMethodPath
Create visitorPOST/api/v1/developer/visitors
Get / Update / Delete visitorGET / PUT / DELETE/api/v1/developer/visitors/{id}
Assign NFC / PIN / QR / license platePUT/api/v1/developer/visitors/{id}/<credential>

Access Policy (15 endpoints) ​

Define when and where users/groups can access doors.

  • Access Policies — CRUD at /api/v1/developer/access_policies[/{id}]
  • Holiday Groups — CRUD at /api/v1/developer/access_policies/holiday_groups[/{id}]
  • Schedules — CRUD at /api/v1/developer/access_policies/schedules[/{id}]

Credential Management (16 endpoints) ​

Manage NFC cards, Touch Passes, PIN codes, and QR codes independently of users.

OperationMethodPath
Generate PINPOST/api/v1/developer/credentials/pin_codes
NFC enrollment sessionPOST / GET / DELETE/api/v1/developer/credentials/nfc_cards/sessions[/{id}]
NFC card CRUDGET / PUT / DELETE/api/v1/developer/credentials/nfc_cards/tokens[/{token}]
Import third-party NFCPOST/api/v1/developer/credentials/nfc_cards/import
Touch Pass list / searchGET / POST/api/v1/developer/credentials/touch_passes[/search]
Download QR code imageGET/api/v1/developer/credentials/qr_codes/download/{visitor_id}

Space / Door Management (13 endpoints) ​

Control doors, door groups, locks, and emergency states.

OperationMethodPath
Door group topologyGET/api/v1/developer/door_groups/topology
Door group CRUDPOST / GET / PUT / DELETE/api/v1/developer/door_groups[/{id}]
Door queryGET/api/v1/developer/doors[/{id}]
Remote unlockPUT/api/v1/developer/doors/{id}/unlock
Lock ruleGET / PUT/api/v1/developer/doors/{id}/lock_rule
Emergency statusGET / PUT/api/v1/developer/doors/settings/emergency

Device Management (4 endpoints) ​

OperationMethodPath
List devicesGET/api/v1/developer/devices
Access method settingsGET / PUT/api/v1/developer/devices/{device_id}/settings
Trigger doorbellPOST/api/v1/developer/devices/{device_id}/doorbell

System Log (4 endpoints) ​

OperationMethodPath
Fetch logsPOST/api/v1/developer/system/logs
Export logsPOST/api/v1/developer/system/logs/export
Fetch log resourceGET/api/v1/developer/system/logs/resource/{id}
Fetch static resourceGET/api/v1/developer/system/static/{path}

UniFi Identity (6 endpoints) ​

OperationMethodPath
Send invitationsPOST/api/v1/developer/users/identity/invitations
Manage resource assignmentsGET / PUT/api/v1/developer/users/{id}/identity/assignments
Group resource assignmentsGET / PUT/api/v1/developer/user_groups/{id}/identity/assignments

Notification (6 endpoints) ​

  • WebSocket — connect to /api/v1/developer/devices/notifications for real-time events
  • Webhook — CRUD at /api/v1/developer/webhooks/endpoints[/{id}]

API Server (2 endpoints) ​

OperationMethodPath
Upload HTTPS certificatePOST/api/v1/developer/api_server/certificates
Delete HTTPS certificateDELETE/api/v1/developer/api_server/certificates

Common Error Codes ​

CodeMeaning
CODE_PARAMS_INVALIDInvalid parameters
CODE_AUTH_FAILEDAuthentication failed
CODE_ACCESS_TOKEN_INVALIDToken invalid or expired
CODE_UNAUTHORIZEDToken lacks required permission scope
CODE_RESOURCE_NOT_FOUNDResource does not exist
CODE_OPERATION_FORBIDDENOperation not allowed
CODE_NOT_EXISTSItem does not exist
CODE_OTHERS_UID_ADOPTED_NOT_SUPPORTEDAPI unavailable after Identity Enterprise upgrade

Tooling ​

Import into Swagger UI / Postman ​

bash
# Swagger UI — use the raw URL
https://raw.githubusercontent.com/Yudefine/unifi-access-api-openapi/main/openapi.yaml

# Or preview locally with Redocly
npx @redocly/cli preview-docs openapi.yaml

Generate a Client SDK ​

bash
# TypeScript
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml -g typescript-fetch -o ./client

# Python
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml -g python -o ./client-python

Validate the Spec ​

bash
npx @redocly/cli lint openapi.yaml

Security Notes ​

  • Always use HTTPS (port 12445). The certificate is self-signed by default.
  • Never expose your API token in client-side code or public repositories.
  • Apply the principle of least privilege when selecting token permission scopes.
  • Consider firewall rules to restrict API access to trusted networks.
  • Implement rate limiting on your side — the server returns HTTP 429 when throttled.