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.

​

Deploying before users exist

You don’t have to assign the Runlayer app in your identity provider (for example Okta) before you push AI Watch through MDM. The organization API key authenticates the device, so AI Watch installs, syncs its settings, and sends scans whether or not the person using the device has a Runlayer account yet. Assigning the app first is still the recommended order. Until a device’s username matches a Runlayer user:

• Shadow AI discoveries show the raw device username instead of a person, and the username is listed under Settings → User mapping.
• Sessions and hook audit events are held, not dropped, and attributed once the username resolves (see Buffered Activity). Older events can take a few hours to appear after the match.
• User, team, and group policy rules don’t apply yet. The device gets its deployment’s settings, or the organization default once policy rules are enabled. A device rule still applies.
• Local tool calls (such as terminal commands and file edits) and browser prompts aren’t content-scanned, so Protect and Enforce let them through. MCP source governance still applies, because it is set for the whole organization.
• Skill sync waits until the device has a user.

Once your identity provider provisions the user, or they sign in, the device’s next scan or hook event matches them automatically through Automatic Resolution. Match the username yourself only when it doesn’t clearly point to one user.

​

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