> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/unifi-integration-setup.md).

# UniFi Integration Setup

### Getting Started

Use this guide to connect UniFi to your BalkanID tenant. You will need credentials from your UniFi Portal and access to the Integrations section in BalkanID.

BalkanID connects to the **UniFi Access** application running on your own UniFi Console. It reads users, user groups, access policies, doors and door groups, and the credentials assigned to each user, so that physical access can be reviewed alongside the rest of your application access.

{% hint style="info" %}
UniFi Access **1.9.1 or later** is required. Group-based features require UniFi Access **2.2.6 or later**.

The UniFi Access API is **not available after upgrading to UniFi Identity Enterprise**. If your console has been upgraded, BalkanID cannot extract data from it.
{% endhint %}

#### Requirements:

Before you begin, collect the following values from UniFi:

* **Host**
* **API Token**

### Configure UniFi within your BalkanID tenant

1. To find the **Host** and **API Token**, sign in to your UniFi Portal at <https://account.ui.com/login>.
2. Select the UniFi Console where the UniFi Access application is installed.
3. Go to **Access** > **Settings** > **General** > **Advanced**, then open **API Token**.
4. Click **Create New**, enter a key name and a validity period, select the permission scopes listed under [Integration Scopes](#integration-scopes) below, then click **Create**.
5. Copy your API Token and store it safely. The token is displayed only once, so it cannot be retrieved later.
6. Your Host is the IP address or domain name of the UniFi Access application server. BalkanID connects to it over HTTPS on port `12445`, so make sure that port is reachable from BalkanID.
7. In BalkanID, go to **Integrations** and click **Add integration**.

<div data-with-frame="true"><figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2F1bEkyF4eKAI3kyzu391y%2Funifi-add-integration.png?alt=media" alt="The BalkanID Integrations page, with the Add integration button in the top right of the toolbar."><figcaption><p>Integrations</p></figcaption></figure></div>

8. Search for **UniFi**, select it, then click **Next**.

<div data-with-frame="true"><figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FEsqp4gFwL7yNGAV5ZMTM%2Funifi-connect-application.png?alt=media" alt="The Connect a new application step with UniFi searched for and selected, showing a check mark on the UniFi card."><figcaption><p>Connect a new application</p></figcaption></figure></div>

9. Paste your **Host** and **API Token** into the corresponding fields, then click **Next**.

<div data-with-frame="true"><figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FfKAmt1UjmDNpeEkkRsVE%2Funifi-direct-configuration.png?alt=media" alt="The Direct Configuration extraction type selected, showing the Host and API Token fields."><figcaption><p>Direct Configuration</p></figcaption></figure></div>

10. Fill **Optional Configuration**, if required.

<div data-with-frame="true"><figure><img src="https://2975852473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbVGYwk8aSk5yI1GDPEW9%2Fuploads%2FZbipc8nl8LTFl5YsVIaj%2Foptional-configuration.png?alt=media" alt="The Optional Configuration step, showing Reviewer Settings on the left and Select Fulfillment options on the right."><figcaption><p>Optional Configuration</p></figcaption></figure></div>

11. Once you have filled in the information, click **Save**. Your integration is now configured and you will see the status of the integration displayed alongside other integrations on the Integrations page. When data is available, the integration Status column will read **Connected** and the integration Message will read **Data available**.

### Integration Scopes

Select all four permission scopes below when you create the API Token. BalkanID only reads from UniFi Access and never modifies access.

| Read Only Scopes                                                                                                                                                                                                                                                                                                                                                                   | Lifecycle Management Scopes |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| <p><strong>view:user</strong> — users and user groups, including group membership<br><strong>view:policy</strong> — access policies, and which users and groups they are granted to<br><strong>view:space</strong> — doors and door groups, and the doors each policy covers<br><strong>view:credential</strong> — NFC cards, PIN codes and touch passes assigned to each user</p> | N/A                         |

{% hint style="info" %}
BalkanID records only the identifier and status of each credential. NFC card tokens and PIN values are never read or stored. License plates and visitor records are not extracted.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/unifi-integration-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.