> ## Documentation Index > Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt > Use this file to discover all available pages before exploring further. # User and Identity Mapping > How AI Watch maps device usernames to Runlayer users for Shadow AI, endpoint hooks, and Sessions AI Watch uses one organization API key for the whole deployment. That key identifies the tenant, not the person using the device, so Runlayer maps device identity to a Runlayer user before showing Shadow AI discoveries, Sessions telemetry, or endpoint-hook audit events. Good identity mapping answers three questions: * Which physical device produced this scan or hook event? * Which OS username was active on that device? * Which Runlayer user should own the resulting discovery or activity? ## What AI Watch Sends AI Watch attaches device context to scans and org-key hook events: | Field | Purpose | | ------------------- | ------------------------------------------------------------------------- | | `device_id` | Stable per-device identifier stored locally and reused by scans and hooks | | `hostname` | Device name for investigation and audit context | | `os` / `os_version` | Operating system context | | `username` | OS login username detected on the device | Package-based AI Watch reads the OS username from device metadata for scans and hooks. For one-off or custom CLI scans, you can override attribution with `runlayer scan --username `. For legacy enrollment flows, deployment-specific username fields may also be used. Prefer full email values when you do use an override; they reduce collisions across shared or multi-domain organizations. ## Automatic Resolution Runlayer resolves a raw device username to a single active Runlayer user inside the same organization. It stops at the first unique match: 1. Exact email match, such as `alex@example.com` 2. `identity_attributes.username` from directory sync or user metadata 3. Email local-part match, such as `alex` for `alex@example.com` 4. Name-pattern matches, such as `first.last`, `firstlast`, first initial + last name, first name, or last name 5. Persisted AI Watch mappings from prior scans or admin matches If a username matches multiple users, Runlayer leaves it unresolved instead of guessing. If the same device later resolves through a scan, hook event, or admin match, Runlayer links future activity to that user. ## Unresolved Usernames Unresolved usernames appear in **Settings → User mapping**. Use this workflow when a device username cannot be matched automatically or was intentionally left unresolved because the match was ambiguous. Go to **Settings** → **User mapping**. Each row shows the raw username, how many devices reported it, and when it was last seen. Search for the Runlayer user, then click **Match**. The mapping applies to all unresolved devices reporting that username in your organization. Run **Detect Re-analysis** when you want existing Shadow AI inventory to pick up the new mapping immediately. Future scans and hook events use the mapping automatically. Manual matches are recorded in the audit log with the admin, raw username, matched user, and affected device count. ## Buffered Activity Hook and Sessions events can arrive before Runlayer knows which user a device username belongs to. In org-key deployments, Runlayer buffers unattributed hook activity instead of dropping it. A later successful scan, admin username match, or device back-link can replay that buffered activity so Sessions and audit logs show the correct user. This means there can be a short delay between resolving a username and seeing older hook/session activity appear. ## Avoiding Bad Matches * Keep Runlayer users in sync with your identity provider so emails and names are current. * Populate `identity_attributes.username` when your OS usernames do not match email local-parts. * Prefer full email usernames for custom scans or legacy enrollment overrides. * Avoid broad shared usernames like `admin`, `developer`, or `user`; they are likely to stay unresolved or ambiguous. * For shared workstations, only add a manual match when the OS username uniquely identifies one Runlayer user. ## Troubleshooting Attribution If an attribution looks wrong after username resolution, use [Troubleshooting: Interpreting Discovery Results](/shadow-ai/troubleshooting#interpreting-discovery-results) as the canonical workflow for checking whether the finding came from config on disk, project paths, shared devices, or username resolution. ## Related Resources Discover shadow MCP servers, skills, and plugins Diagnose attribution and deployment issues Refresh Shadow AI inventory after changes Install and configure AI Watch