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 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: a stable per-device identifier (stored locally and reused by scans and hooks), the device hostname, the operating system and version, and the 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 <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, using directory identity attributes, email, name data, and previously confirmed AI Watch mappings. Resolution is conservative: if a username could correspond to more than one user, 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. 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, hook activity that arrives before a username is resolved is retained rather than dropped, and is attributed once resolution completes — so Sessions and audit logs eventually 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 each user’s directory username (the identity_attributes.username field, synced from your identity provider) 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