---
title: "List identities"
method: GET
path: "/v1/nhi/identities"
tags: ["NHI Identities"]
---

# List identities

`GET /v1/nhi/identities`

## Request

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

List the non-human identities (NHIs) of the workspace.

The response contains a page of identities and a pagination cursor to retrieve the next page.

Filters that take a list accept comma-separated values. The `__nin` variant of a filter
excludes the identities that match it.

An identity id stays the same while the identity holds the same secrets. When a secret is
rotated, or two identities merge, the id can change and the owners set on the previous id
are not carried over. Look up the identity again rather than storing its id.

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

## Query parameters

- `cursor` string
- `per_page` integer
- `search` string
- `ordering` 'id' | '-id'
- `source__in` string
- `env__in` string
- `policy__in` string
- `risk_criticality__in` string
- `validity__in` string
- `principal_type__in` string
- `owner_id__in` string
- `vault_source_id__in` string
- `consumer_source_id__in` string
- `endpoint_source_id__in` string
- `provider_source_id__in` string
- `detector_group_name__in` string
- `detector_type__in` string
- `secret_family__in` string
- `secret_category__in` string
- `secret_provider__in` string
- `has_owner` boolean
- `has_detector` boolean
- `is_admin` boolean
- `hmsl_hash` string

## Response `200`

A page of identities.

- 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`.

## Other responses

- `400`: Invalid data
- `401`: Invalid API key
- `403`: Permission denied
- `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/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)