> 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/mapping-and-unmapping-identities-to-employees.md).

# Mapping and Unmapping Identities to Employees

## Overview

Mapping connects each application identity to the employee behind it. BalkanID uses these mappings in entitlement discovery, access reviews, offboarding and risk analysis, so accurate mappings are the foundation for most of what you do in your tenant. Many identities are mapped automatically when your integrations sync. Use the steps on this page to map the rest and to correct existing mappings.

An identity can have two kinds of employee mappings:

* **Owner:** the employee the identity belongs to or who is accountable for it. This covers both an employee's own account and a service account that an employee is responsible for. An identity has one owner.
* **Accessible by:** employees who can use the identity, for example through shared or delegated use. You can add several. An owner cannot also be listed as accessible by.

The *Identities* page shows both in the **Owner** and **Accessible by** columns. The **Agents** column lists the agents that use each identity. Use the **Mapping Status** filter (**Mapped** or **Unmapped**) to find identities with or without an owner.

<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%2FcMm9yrQGZnl9m9yPGHQd%2Fidentities-owner-columns-v2.png?alt=media" alt="Identities page listing service accounts with Dhruv Shah as owner, employees under Accessible by, and the agents that use each identity in the Agents column"><figcaption><p>Owner, Accessible by and Agents columns on the Identities page</p></figcaption></figure></div>

On a person's page, the **Identities** tab has an **Owned** / **Accessible by** toggle, so you can see the identities that person owns and the identities they can use.

<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%2F1M7MKYWC9sUgLmlWv0BK%2Fperson-identities-accessible-by-v2.png?alt=media" alt="Dhruv Shah&#x27;s person page on the Identities tab with the Accessible by toggle selected, listing the identities Dhruv can use but does not own"><figcaption><p>The Accessible by toggle on a person's Identities tab</p></figcaption></figure></div>

### Owners set by an application

If an application integration sets the owner of an identity, you cannot change that owner in BalkanID. An information icon next to the owner on the identity's page says so. To change it, change it in the application. You can still add **accessible by** employees.

### Manually unmapped identities

You can explicitly **unmap** an identity from an employee. Unmapping removes the employee association and stops integration syncs from re-establishing it automatically. The **Owner** column then shows **Unmapped**, and its tooltip says the identity was manually unmapped, so you can tell it apart from an identity that has never been mapped.

To map a manually unmapped identity again, map it to an employee using either method below. This clears the unmapped state.

## Before you begin

* Make sure your applications have synced. Go to the *Integrations* page under *Configure* and check that data has been fetched.
* The **Employee Relations CSV** application must be installed and active for your tenant. Both the guided flow and the CSV upload use it. If it is missing, BalkanID prompts you to install it.

You can map identities in two ways:

1. [In the application](#map-identities-in-the-application), for a few identities at a time.
2. [With a CSV file](#map-identities-with-a-csv-file), for bulk changes.

## Map identities in the application

1. Go to the *Identities* page under *Entities*.
2. Select the identities you want to map. The **Map identities** button shows the number of selected identities.
3. Click **Map identities**. A side view opens with the selected identities listed under **To be mapped**.
4. Under **Owner**, select the employee the identities belong to. Under **Accessible by**, select one or more employees who can use them. If a selected identity already has an owner, the side view shows the current owner and warns you before replacing it.

<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%2Fc13C9YaUTxcDk8gNbMWs%2Fidentities-map-side-view-v2.png?alt=media" alt="Map identities side view with two identities selected, Dhruv Shah chosen as owner, a warning that this replaces the current owner, and two employees under Accessible by"><figcaption><p>Map identities side view, warning before the current owner is replaced</p></figcaption></figure></div>

5. Click **Map identities**. To make each identity's application owner its owner instead, click **Map identities to Application Owner**.
6. A message confirms that your change is being processed. It appears on the *Identities* page within 2–3 minutes.

If an integration sets the owner of a selected identity, the **Owner** field is read-only. You can still add **accessible by** employees.

## Map identities with a CSV file

1. Go to the *Identities* page under *Entities*. Make sure no identities are selected. The **Map identities** button shows the number of unmapped identities in your tenant.
2. Click **Map identities** to open the side view.
3. Under **Step 1: Download mapping template**, open the drop-down and choose **Download all identities** or **Download unmapped identities**, then click the button. To get a list of employee IDs and emails to copy from, choose **Download employees**.

<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%2Fg1aKYyjtg6yYgnTxUZx8%2Fidentities-bulk-mapping-download-v2.png?alt=media" alt="Map identities side view with the download menu open, offering Download all identities, Download unmapped identities and Download employees"><figcaption><p>Download options in the Map identities side view</p></figcaption></figure></div>

4. Fill in the file. For each row, enter the employee in **Employee Email** or **Employee ID**, and set **Relation Type** to one of the [relation types](#relation-types).
5. Under **Step 2: Upload new mapping**, upload the edited file. If your file uses different column names, click **Review Column Mapping** to match them to BalkanID's columns.

Rows that cannot be processed, for example an unknown employee or a change to an owner that an application sets, are skipped. A warning lists each skipped row and the reason. Valid rows in the same file are still applied.

If you downloaded the file from BalkanID, mappings that came from an integration have `integrations` in the **Source System** column. These rows are skipped when you upload the file again, so you can leave them in the file.

### Relation types

| Value                  | Use it to                                                                                                                                             |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `owner`                | Set the owner: an account an employee uses directly, or a service account an employee is responsible for. This is the default if the column is blank. |
| `accessible_by`        | Add an employee who can use the identity. Add one row per employee.                                                                                   |
| `remove_owner`         | Remove an owner that was set manually. Leave the employee columns blank.                                                                              |
| `remove_accessible_by` | Remove an employee from accessible by.                                                                                                                |
| `unmapped`             | Remove the existing mapping and stop integration syncs from re-establishing it. Leave the employee columns blank.                                     |

Files that still use **IS** or **OWNS** are accepted and treated as `owner`.

## Unmap identities

Unmapping removes an owner or accessible by employee that was added manually. When no employee is left on the identity, the **Owner** column shows **Unmapped**.

### In the application

1. Go to the *Identities* page under *Entities* and select the identities you want to change.
2. Click **Unmap identities** to open the side view.
3. On the **Users** tab, select the owner or the accessible by employees to remove from each identity. Owners set by an integration show a lock and cannot be removed here.

<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%2F1BOqDeQeVTbl1BGHos0I%2Fidentities-unmap-side-view-v2.png?alt=media" alt="Unmap identities side view on the Users tab with one accessible by employee selected for removal and the Remove user mappings button"><figcaption><p>Unmap identities side view: remove one employee without clearing the mapping</p></figcaption></figure></div>

4. Click **Remove user mappings** at the bottom of the side view. The button shows how many mappings will be removed.
5. The change appears within 2–3 minutes.

### With a CSV file

1. Download the identities from the **Map identities** side view, as described above.
2. For each identity, set **Relation Type** to `unmapped` and leave **Employee Email** and **Employee ID** blank. To remove only the owner or one accessible by employee, use `remove_owner` or `remove_accessible_by` instead.
3. Upload the edited file in the same side view.

## Map identities to agents

You can also record which agents use an identity. Agents are always mapped as **accessible by**, never as owner, and they appear in the **Agents** column and in the **Accessible by** section of the identity's page. This uses the **Agent Relations CSV** application, which must be installed for your tenant.

1. Go to the *Identities* page under *Entities* and select the identities.
2. Click **Map identities**, then select the **Agents** tab.
3. Under **Agents**, select one or more agents. Each selected identity is linked to every agent you choose.
4. Click **Map&#x20;*****n*****&#x20;identities to&#x20;*****n*****&#x20;agents**.

<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%2Fxs2TbEzYVJBsGM5NTn84%2Fidentities-map-to-agents-v2.png?alt=media" alt="Map identities side view on the Agents tab with two identities selected and two agents chosen"><figcaption><p>Mapping identities to agents</p></figcaption></figure></div>

To remove agents from an identity, select the identity, click **Unmap identities** and use the **Agents** tab. This does not delete the identity or the agent. For the file format and more detail, see [Mapping Identities and Credentials to Agents](https://docs.balkan.id/agents/mapping-identities-and-credentials-to-agents.md).

## CSV format

The file you download from BalkanID already uses this format. If you build the file yourself, use these columns.

| Column                                | Description                                                                                                                          |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **App**                               | The app of the identity, for example `okta`. Use it on its own only if you have exactly one integration of that app.                 |
| **Integration ID**                    | The integration the identity belongs to, for example `okta/01KF0DJF3JAT`. Preferred over **App**. If you give both, they must match. |
| **Employee ID**                       | The BalkanID ID of the employee.                                                                                                     |
| **Employee Email**                    | The employee's work email, matched without regard to case.                                                                           |
| **Target ID**                         | The BalkanID ID of the identity.                                                                                                     |
| **Target Source ID**                  | The identity's ID in its application.                                                                                                |
| **Target Username**                   | The identity's username in the application.                                                                                          |
| **Target Email**                      | The email the identity uses in the application.                                                                                      |
| **Target Type**                       | `identity` (default), `credential` or `agent`. Leave blank or set to `identity` for identities.                                      |
| **Relation Type**                     | See [Relation types](#relation-types).                                                                                               |
| **Source System**                     | Leave as `employee_relations_csv`. `integrations` is reserved for integration syncs.                                                 |
| **Metadata Version** and **Metadata** | Optional. Metadata is JSON, and the two columns must be filled in together.                                                          |
| **Timestamp**                         | Optional. A Unix timestamp in seconds.                                                                                               |

Each row needs:

* **App** or **Integration ID**.
* **Employee ID** or **Employee Email**. Not needed for `unmapped` and `remove_owner`.
* At least one of **Target ID**, **Target Source ID**, **Target Username** or **Target Email**.

### Files from earlier versions

The CSV application was previously called **Relations CSV** and is now **Employee Relations CSV**. Files that use the earlier column names still upload, and BalkanID reads the old names as the new ones:

| Earlier column    | Now             |
| ----------------- | --------------- |
| App ID            | Integration ID  |
| Identity ID       | Target ID       |
| Identity Username | Target Username |
| Identity email    | Target Email    |
| User email        | Employee Email  |

Other earlier columns, such as *Identity name*, *App Name*, *App Description* and the employee name, department and job title columns, are ignored. New files should use the columns above.

## Upload through the BalkanID API (Early Access)

To automate mapping, use the Bulk API. Request an upload URL with `POST /employee-relations/upload-url`, then upload your CSV to the URL it returns. Use `POST /employee-relations/download-url` to export existing mappings. Pass `targetType` as `identity` (the default) or `credential`.

The earlier `/relations/upload-url` and `/relations/download-url` endpoints still work but are deprecated. The download endpoint now returns the columns above. For request details, see the BalkanID API reference at [developer.balkan.id](https://developer.balkan.id).

## Need help?

If something does not map as expected, contact BalkanID Support or your customer success representative.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/mapping-and-unmapping-identities-to-employees.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
