Get identity by filter
GET/intelligence/v1/identities
Requires tenant license idn:response-and-remediation.
Authentication and data segmentation
Intelligence forwards the caller JWT to downstream identity and search services (context client). Enriched results, including non-human identity resolution, are filtered to the caller's Data Segmentation visibility.
Caution: Generic API Management API keys are not tied to a user identity. When Data Segmentation is enabled, API key authentication may fail or return incomplete data because downstream calls require a user context. Use a personal access token or other user-scoped OAuth token. See API keys and Data Segmentation.
Resolves exactly one identity using a single SCIM-style filters expression.
Supported filters
| Filter field | Lookup mode | Notes |
|---|---|---|
| id eq | Human (+ optional non-human identity when feature-flagged) | Resolves human identities by id; when non-human resolution is enabled, a parallel non-human lookup runs. If both match different identities, returns HTTP 409. |
| email eq | Human only | Human identity lookup by email only. |
| opaqueIdentifier eq | Non-human identity only | Parallel nativeIdentity eq on machine-identities and machine-accounts, then name-prefix fallback on machine-accounts. Requires feature flag ISCRR-1905_NHI_TYPE_MACHINE_FILTER_ENABLED; when disabled, returns HTTP 400. |
Single-clause filters only; composite and or expressions are rejected with HTTP 400.
identityGraph deep link
When the tenant has the idg:base license, Human and NHI aggregate responses may include
identityGraph.href, a deep link into the Identity Graph UI for the resolved identity.
Opening the link requires the Identity Graph Read Only user level. The link is omitted
when the tenant lacks idg:base.
Human envelope (type Human)
Embeds the first page (10 items) of each enrichment slice. Each paged slice includes totalCount from upstream X-Total-Count when items is non-empty, and carries a next continuation URL when totalCount exceeds the items returned on this page. Slices are always present (empty uses items [] with no totalCount). privilegedAccess returns the full privileged-access result and never carries next or totalCount. If any enrichment upstream fails, the whole request fails with HTTP 500, except outliers, which is omitted (not an error) when the tenant lacks the IDA-outliers license (upstream 401 or 403).
Non-human identity envelope (type NHI)
Returns flat non-human identity fields at the top level plus correlated machine accounts on the aggregate and a derived block (isOrphaned, authorizedHumanIdentities, blastRadiusSummary). Omits Human-only slices (privilegedAccess, outliers, accessHistory). Account paging via child routes is not yet released. Opaque prefix resolution that deduplicates to one parent identity returns HTTP 200 with matchConfidence partial; multiple distinct parent identities return HTTP 409 with IDC_IDENTITY_AMBIGUOUS and candidate id and displayName values.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 429
- 500
Exactly one identity matched.
Missing or invalid filters, unsupported filter field or operator, composite and or filter combination, or opaqueIdentifier lookup when non-human machine resolution is disabled for the tenant.
Unauthorized - Returned if there is no authorization header, or if the JWT token is expired.
Unauthorized access
No identity matched the filter (detailCode IDC_IDENTITY_NOT_FOUND).
Multiple identities matched the filter (detailCode IDC_IDENTITY_AMBIGUOUS), including human email or id multi-hit, human and machine id eq clash, and non-human opaque resolution ambiguity. Response includes candidates with id and displayName for refinement.
Too Many Requests - Returned in response to too many requests in a given period of time - rate limited. The Retry-After header in the response includes how long to wait before trying again.
Upstream or internal failure. Identity resolution may pass an upstream non-2xx through; enrichment-slice failures are sanitized to a generic HTTP 500.