NAV Navbar
shell

Introduction

The incomplete and unofficial documentation of the UniFi Protect API.

This API documentation page was created with Slate.

Authentication

User Authentication

Authenticate with the username and password of a local user to receive an OAuth Bearer Token.

HTTP Request

POST https://{cloud-key-address}:7443/api/auth

Headers

Key Value Description
Content-Type application/json

Request Body

{"username": my_username, "password": my_password}

If the authentication was successful, you will receive a JSON Response Body containing some general information about your user account.

Example Response Body for 200 OK

{
    "permissions": [
        "user:read,write,delete:$",
        "liveview:create"
    ],
    "lastLoginIp": null,
    "lastLoginTime": null,
    "isOwner": false,
    "localUsername": "your_username",
    "enableNotifications": false,
    "syncSso": false,
    "settings": null,
    "groups": [
        "000000000000000000000000"
    ],
    "cloudAccount": null,
    "alertRules": [],
    "id": "111111111111111111111111",
    "hasAcceptedInvite": false,
    "role": "admin",
    "allPermissions": [
        "user:read,write,delete:$",
        "liveview:create",
        "nvr:read:*",
        "camera:read,readmedia:*"
    ],
    "modelKey": "user"
}

Example Response Body for 401 Unauthorized

{
    "error": "invalid username or password"
}

API Access Key

Use the OAuth Bearer Token to request an API Access Key which is required for API calls that require an accessKey query parameter.

HTTP Request

POST https://{cloud-key-address}:7443/api/auth/access-key

Headers

Key Value Description
Authorization Bearer {your_oauth_bearer_token}

Request Body

No Request Body content is required for this request.

If the authentication was successful, you will receive a JSON Response Body containing your API accessKey.

Example Response Body for 200 OK

{
    "accessKey": "1234567890123:abcdef1234567890abcdef12:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}

The access key consists of three parts using a : as delimiter: {expiration_timestamp_milliseconds}:{user_id}:{access_key_data}.

Part  Type  Description
1  unix timestamp in milliseconds  date and time until which the accessKey is valid
2  24 byte hex data  ID of the user that requested the accessKey
3 128 byte hex data  the access key itself

Example Response Body for 401 Unauthorized

{
    "error": "Unauthorized",
    "type": "AuthenticationError"
}
shell