User and Identity Mapping

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 Enforce 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: 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 <value>. 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 → MDM Configuration → Unresolved usernames. Use this workflow when a device username cannot be matched automatically or was intentionally left unresolved because the match was ambiguous. Manual matches are recorded in the audit log with the admin, raw username, matched user, and affected device count.

​

Buffered Activity

Enforce 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 as the canonical workflow for checking whether the finding came from config on disk, project paths, shared devices, or username resolution.

​

Related Resources