> ## Documentation Index
> Fetch the complete documentation index at: https://hilt.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity Mapping

> Grouping the many identities one person uses into a single person record.

One human shows up in your fleet as several identities — a Linux login on one host, a different login on another, an SSH session, a Teleport session, a laptop. Identity Mapping is where you name the person once and attribute those identities to them, so activity across endpoints and hosts is correlated under one name instead of scattered across a pile of raw logins.

Find it under **Settings → Teams → Identity mapping**. This page requires the **manage users** permission and is available only with PostgreSQL-backed authentication (hidden in static admin mode).

> [!NOTE]
>
> No identity directory is required. Earlier versions of this page could only decorate an observed identity with Okta profile fields, which meant it did nothing at all unless an Okta sync was configured. A mapping is now the person record itself.

***

## How it works

You seed what you know; Hilt derives the rest.

1. You create a person and attribute one or two identities you are sure about — usually their laptop or their main login.
2. When that endpoint connects to a host over SSH, Hilt attaches the destination host **and** the login they used there to the same person, automatically.
3. Those derived links are marked **auto** and keep arriving on their own. There is no list to maintain by hand.

Generic logins (`root`, `ec2-user`, `ubuntu` and similar) are never auto-attributed, since they say nothing about who was driving.

***

## The page

The left rail lists everyone you have created, with the number of identities attributed to each. Search it by name, email, or by any login attributed to them — people are often remembered by a username rather than a name. Selecting someone opens their detail on the right.

***

## Adding a person

Click **Add person**.

| Field | Required | Notes |
| - | - | - |
| **Name** | Yes | The human's name, as you want it to appear throughout the product |
| **Email** | No | Optional context on the record; it is not a login and is never matched against |
| **Their identities** | No | Attribute now, or at any time afterwards |

***

## Attributing identities

From a person's detail pane, click **Attribute an identity**. The picker lists identities the pipeline has actually observed, most active first, and shows enough context to tell one `alice` from another before you commit:

| Shown | Why it matters |
| - | - |
| **Sources** | Every source the name appeared under — Linux user, SSH session, macOS device, Teleport, and so on |
| **Hosts and events** | How widely and how heavily the identity was used |
| **Last seen** | Whether this is live activity or something dormant |
| **Hostnames** | The machines it touched |

Search runs against the full observed set, not just the rows on screen.

Attributing an identity that was seen under several sources creates a link for **each** source, so the whole human is captured rather than one of their logins.

An identity already attributed to someone else stays in the list, greyed out and labelled with its current owner, rather than silently disappearing.

> [!NOTE]
>
> The picker covers identities observed in the **last 7 days**. Something dormant for longer will not appear.

***

## Editing and removing

* **Edit** changes the name or email. Links are keyed to the person record, so renaming never disturbs what is attributed to them.
* The trash icon next to an attributed identity removes that one link. If the link was derived automatically, it may come back the next time the same SSH evidence is seen — remove the seed link instead if you want it to stay gone.
* Deleting a person returns their identities to being unattributed. No activity or event data is deleted.

***

## Merging two people

Sometimes the same human was created twice — `alex.g` on one host and `alex` on another, with nothing in the data tying the two strings together. Use **Fold *person* into…** at the bottom of the detail pane and pick the person to keep.

Every identity moves to the target and the emptied record is removed, so an identity is never owned by two people. A merge is recorded as a human assertion: it outranks every derived link, and re-running the passive linker can never undo it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.