---
title: "Promote identities to incidents"
method: POST
path: "/v1/nhi/identities/promote"
tags: ["NHI Identities"]
---

# Promote identities to incidents

`POST /v1/nhi/identities/promote`

## Request

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

Create a secret incident for the secret of each identity, as the "Promote to incident"
action of the dashboard does. An identity whose secret already has an incident reuses
it and adds its missing occurrences.

One call takes 1 to 100 identities and returns one result for each identity.
To promote more identities, make several calls, one after the other.

An identity is skipped when its secret cannot become an incident: no secret, no secret
hash, or no detector. An identity that is not in the workspace, or whose places cannot be
found any more, is skipped too.

The workspace must have NHI governance activation and NHI incident promotion.
The API token must have the Manager access level or above, or be a service account token.

## Request body

- object
  - `identity_ids` integer[], required: Ids of the identities to promote, as the identity list returns them.

## Response `200`

The outcome of each identity.

- object
  - `created_count` integer, required: Number of identities that got a new incident.
  - `reused_count` integer, required: Number of identities whose secret already had an incident.
  - `skipped_count` integer, required: Number of identities that could not be promoted.
  - `results` object[], required
    - `identity_id` integer, required
    - `outcome` 'created' | 'reused' | 'skipped', required: - `created`: a new incident was created. - `reused`: the secret already had an incident. Its missing occurrences were added. - `skipped`: the identity could not be promoted. `skip_reason` gives the reason.
    - `incident_ids` integer[], required: Ids of the incidents of the identity. Empty when the identity is skipped.
    - `skip_reason` 'unknown_credential' | 'no_static_secret' | 'no_secret_hash' | 'no_detector' | 'null', nullable, required: Why the identity was skipped, `null` otherwise: - `unknown_credential`: the identity is not in the workspace, or none of its places can be found any more (for example, its source was removed). - `no_static_secret`: the identity holds no secret. - `no_secret_hash`: the secret has no hash to match incidents with. - `no_detector`: no detector classifies the secret.

## Other responses

- `400`: No identity, or more than 100 identities.
- `401`: Invalid API key
- `403`: Permission denied
- `404`: NHI governance or NHI incident promotion is not active for the workspace.
- `503`: API under maintenance

## Changes

- **2026-11-02** `5829df7b9045`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/gitguardian/apis/gitguardian-api/changes/v1/nhi/identities/promote/post.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)