Overview
This section provides an introduction to essential concepts related to working with APIs, including API tokens, HTTP status codes, success and error codes, HTTP verbs, and API hosts.
API Token
To authenticate API requests with UniFi Access, you need to utilize API tokens associated with your account. If a request includes a deleted or expired token, the service will return an authentication error. The Authorization Token is obtained from UniFi Portal.
HTTP Status Code Reference
| 200 | OK | Everything worked as expected. |
| 400 | Bad Request | The request is unacceptable, often due to missing required parameters. |
| 401 | Unauthorized | The request lacks a valid API token for authentication. |
| 402 | Request Failed | The request contains valid parameters, but failed for some reason. |
| 403 | Forbidden | The API token used does not have the necessary permissions to perform the request. |
| 429 | Too Many Requests | Too many requests were sent to the API in a short amount of time. |
| 500, 502, 503, 504 | Server Errors | Something went wrong on UniFi Access's end during request processing. |
Success Code
json
{
"code": "SUCCESS",
"msg": "success"
}| Code | Message |
| SUCCESS | Success |
Error Code
json
{
"code": "CODE_PARAMS_INVALID",
"msg": "Invalid parameters."
}| Code | Message |
| CODE_PARAMS_INVALID | The provided parameters are invalid. |
| CODE_SYSTEM_ERROR | An error occurred on the server's end. |
| CODE_RESOURCE_NOT_FOUND | The requested resource was not found. |
| CODE_OPERATION_FORBIDDEN | The requested operation is not allowed. |
| CODE_AUTH_FAILED | Authentication failed. |
| CODE_ACCESS_TOKEN_INVALID | The provided access token is invalid. |
| CODE_UNAUTHORIZED | You are not allowed to perform this action. |
| CODE_NOT_EXISTS | The requested item does not exist. |
| CODE_USER_EMAIL_ERROR | The provided email format is invalid. |
| CODE_USER_ACCOUNT_NOT_EXIST | The requested user account does not exist. |
| CODE_USER_WORKER_NOT_EXISTS | The requested user does not exist. |
| CODE_USER_NAME_DUPLICATED | The provided name already exists. |
| CODE_USER_CSV_IMPORT_INCOMPLETE_PROP | Please provide both first name and last name. |
| CODE_ACCESS_POLICY_USER_TIMEZONE_NOT_FOUND | The requested workday schedule could not be found. |
| CODE_ACCESS_POLICY_HOLIDAY_TIMEZONE_NOT_FOUND | The requested holiday schedule could not be found. |
| CODE_ACCESS_POLICY_HOLIDAY_GROUP_NOT_FOUND | The requested holiday group could not be found. |
| CODE_ACCESS_POLICY_HOLIDAY_NOT_FOUND | The requested holiday could not be found. |
| CODE_ACCESS_POLICY_SCHEDULE_NOT_FOUND | The requested schedule could not be found. |
| CODE_ACCESS_POLICY_HOLIDAY_NAME_EXIST | The provided holiday name already exists. |
| CODE_ACCESS_POLICY_HOLIDAY_GROUP_NAME_EXIST | The provided holiday group name already exists. |
| CODE_ACCESS_POLICY_SCHEDULE_NAME_EXIST | The provided schedule name already exists. |
| CODE_ACCESS_POLICY_SCHEDULE_CAN_NOT_DELETE | The schedule could not be deleted. |
| CODE_ACCESS_POLICY_HOLIDAY_GROUP_CAN_NOT_DELETE | The holiday group could not be deleted. |
| CODE_CREDS_NFC_HAS_BIND_USER | The NFC card is already registered and assigned to another user. |
| CODE_CREDS_DISABLE_TRANSFER_UID_USER_NFC | The UniFi Identity Enterprise user's NFC card is not transferrable. |
| CODE_CREDS_NFC_READ_SESSION_NOT_FOUND | Failed to obtain the NFC read session. |
| CODE_CREDS_NFC_READ_POLL_TOKEN_EMPTY | The NFC token is empty. |
| CODE_CREDS_NFC_CARD_IS_PROVISION | The NFC card is already registered at another site. |
| CODE_CREDS_NFC_CARD_PROVISION_FAILED | Please hold the NFC card against the reader for more than 5 seconds. |
| CODE_CREDS_NFC_CARD_INVALID | The card type is not supported. Please use a UA Card. |
| CODE_CREDS_NFC_CARD_CANNOT_BE_DELETE | The NFC card could not be deleted. |
| CODE_CREDS_PIN_CODE_CREDS_ALREADY_EXIST | The PIN code already exists. |
| CODE_CREDS_PIN_CODE_CREDS_LENGTH_INVALID | The PIN code length does not meet the preset requirements. |
| CODE_SPACE_DEVICE_BOUND_LOCATION_NOT_FOUND | The device's location was not found. |
| CODE_DEVICE_DEVICE_VERSION_NOT_FOUND | The firmware version is up to date. |
| CODE_DEVICE_DEVICE_VERSION_TOO_OLD | The firmware version is too old. Please update to the latest version. |
| CODE_DEVICE_DEVICE_BUSY | The camera is currently in use. |
| CODE_DEVICE_DEVICE_NOT_FOUND | The device was not found. |
| CODE_DEVICE_DEVICE_OFFLINE | The device is currently offline. |
| CODE_OTHERS_UID_ADOPTED_NOT_SUPPORTED | The API is not available after upgrading to Identity Enterprise. |
| CODE_HOLIDAY_GROUP_CAN_NOT_DELETE | The holiday group could not be deleted. |
| CODE_HOLIDAY_GROUP_CAN_NOT_EDIT | The holiday group could not be edited. |
| CODE_DEVICE_WEBHOOK_ENDPOINT_DUPLICATED | The provided endpoint already exists. |
| CODE_DEVICE_API_NOT_SUPPORTED | The API is currently not available for this device. |
HTTP Verbs
| HTTP Method | Description |
| GET | Used for retrieving objects. |
| POST | Used for creating objects or performing custom actions. |
| PUT | Used for replacing objects or collections. |
| DELETE | Used for deleting objects. |
API Host
The Open API Server is hosted on port 12445 and can be accessed via HTTPS at https://console-ip:12445.
The server certificate is self-generated and untrusted.
Request Header
The header for a request contains the following information:
| Parameter | Required | Type | Description | Example |
| Authorization | T | String | Token required for authentication and access control. | Authorization: Bearer wHFmHRuX4I7sB2oDkD6wHg |
Response Schema
The response for a request contains the following information:
json
{
"code": "SUCCESS",
"msg": "success",
"data": {}
}- code: Represents the result of request handling and indicates success or failure.
- msg: Represents the error description if the code is not equal to 1.
- data: Represents the data of API requests.