---
title: "Retrieve an identity"
method: GET
path: "/v1/nhi/identities/{identity_id}"
tags: ["NHI Identities"]
---

# Retrieve an identity

`GET /v1/nhi/identities/{identity_id}`

## Request

- Base URL: `https://api.gitguardian.com`
- URL: `https://api.gitguardian.com/v1/nhi/identities/{identity_id}`
- Auth: HTTP bearer

Retrieve a non-human identity, with its permissions and a summary of its secrets.

The API token must have the Manager access level or above, or be a service account token.

## Path parameters

- `identity_id` integer, required

## Response `200`

The identity.

- object
  - `id` integer, required
  - `name` string, required: Display name of the identity.
  - `hmsl_hash` string, nullable: HasMySecretLeaked hash of the secret value behind the identity, the key that links it to incidents and to other products. `null` when the identity holds no hashed secret.
  - `environments` string[], required
  - `companies` string[], required: Services that the secrets of the identity give access to.
  - `detectors` object[]: Detectors that classify the secrets of the identity.
    - `name` string, required
    - `display_name` string, nullable
  - `detector_types` string[]
  - `secret_categories` string[]
  - `secret_families` string[]
  - `secret_providers` string[]
  - `provider` object, nullable: Source that declares the identity, such as a cloud account.
    - `id` integer, required: Id of the source, as returned by the source list. The `*_source_id__in` filters of the identity list take it.
    - `type` string, required: Type of the source.
    - `name` string, required: Display name of the source.
  - `secrets_managers` object[], required: Secrets managers that store a secret of the identity.
    - `id` integer, required: Id of the source, as returned by the source list. The `*_source_id__in` filters of the identity list take it.
    - `type` string, required: Type of the source.
    - `name` string, required: Display name of the source.
  - `consumers` object[], required: Consumers, such as Kubernetes clusters or CI systems, that use a secret of the identity.
    - `id` integer, required: Id of the source, as returned by the source list. The `*_source_id__in` filters of the identity list take it.
    - `type` string, required: Type of the source.
    - `name` string, required: Display name of the source.
  - `endpoints` object[], required: Endpoints that hold a secret of the identity.
    - `id` integer, required: Id of the source, as returned by the source list. The `*_source_id__in` filters of the identity list take it.
    - `type` string, required: Type of the source.
    - `name` string, required: Display name of the source.
  - `last_used_at` string, date-time, nullable
  - `created_at` string, date-time, nullable
  - `breached_policies` string[], required: NHI policies that the identity breaches.
  - `risk_criticality` 'low' | 'medium' | 'high' | 'critical', required
  - `owners` object[], required
    - `id` integer, required: Id of the owner, as returned by the identity owners endpoints.
    - `email` string, email, required
    - `user_id` integer, nullable: Id of the GitGuardian user linked to this owner.
  - `is_admin` boolean, nullable: Whether the identity has admin-level permissions. `null` when unknown.
  - `validity` 'valid' | 'invalid' | 'failed_to_check' | 'no_checker' | 'unknown', nullable: Validity of the identity: the highest-ranked validity among its secrets. `null` when the identity holds no secret.
  - `checked_at` string, date-time, nullable: Date of the validity check that gives `validity`.
  - `permissions` string[], required
  - `secret_summaries` object[], required: Count of the secrets of the identity, per detector.
    - `detector_name` string, nullable
    - `detector_display_name` string, nullable
    - `total_count` integer, required
  - `analysis` object, nullable: What the secret analyzer reports about the provider-side account behind the secrets. `null` when no analyzer ran on the secrets of the identity.
    - `scopes` string[]
    - `risks` string[]
    - `inferred_profile` string, nullable
    - `owner` object, nullable
    - `secret_info` object, nullable
    - `organizations` object[]
    - `provider_attribution` object, nullable
    - `management` object, nullable

## Other responses

- `401`: Invalid API key
- `403`: Permission denied
- `404`: Identity not found
- `503`: API under maintenance

## Changes

- **2026-10-21** `426ea32f227a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/gitguardian/apis/gitguardian-api/changes/v1/nhi/identities/:identity_id/get.md)

---

[API](https://skmtc.dev/gitguardian/apis/gitguardian-api.md) - [All operations](https://skmtc.dev/gitguardian/apis/gitguardian-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gitguardian/apis/gitguardian-api/revisions/5829df7b9045?raw)