---
title: "List a machine/user's honeytoken deployments (read-only)"
method: GET
path: "/v1/honeytokens/endpoint-deployments"
tags: ["Honeytokens"]
---

# List a machine/user's honeytoken deployments (read-only)

`GET /v1/honeytokens/endpoint-deployments`

**⚠️ Beta Version**: This endpoint is in beta and may be subject to changes in future releases.

Lists the live honeytoken deployments for a machine and OS user, **read-only**.

Unlike the `POST`, this call mints nothing and creates no Endpoint/EndpointUser —
an unknown `(machine_id, username)` simply yields an empty list. It powers the
`ggshield … --remove-only` cleanup mode: the client reads the current state and
applies only the `delete` actions (removing revoked honeytokens from disk) without
ever planting.

Each entry has the same shape as the `POST` response, carrying an `action`
(`write` / `delete`), the placement `config`, and the `token` credentials (the
revoked key on a `delete` lets the client verify the on-disk profile is the decoy
before removing it).

Authorize with the `honeytokens:write` scope (the cleanup flow also PATCHes
`removed`, so the same write-scoped fleet SAT is used).

## Query parameters

- `machine_id` string, required
- `username` string, required

## Response `200`

The live honeytoken placements for this machine/user (possibly empty).

- object — Desired honeytoken placements for a machine/user.
  - `deployments` object[]
    - `id` string, uuid — Deployment id (use it for the status-update PATCH).
    - `type` string
    - `method` 'aws_credentials' | 'aws_config_profile' — Placement method (sibling discriminator) — drives how the client materializes `config` (which file + section format).
    - `config` object — Method-specific placement payload. The `method` is a **sibling** field on the deployment (not nested here) and selects how the client materializes the placement: the AWS credentials file writes `[profile_name]`, the AWS config file writes `[profile profile_name]`. GIM owns *what* (filename, profile name); the client owns *where* (the directory, composed from `method` + OS, e.g. `~/.aws/`).
      - `filename` string, required — Basename of the on-disk file. The client composes the directory from the method + OS; only the basename is server-controlled (and overridable).
      - `profile_name` string, required — Named section/profile the client writes/removes. Lets the client manage the placement by `(filename, profile_name)` — and delete a revoked one by name, without needing the secret.
    - `status` 'pending' | 'planted' | 'failed'
    - `action` 'write' | 'delete' — `write` — the honeytoken should be present (`token` holds the credentials to write). `delete` — a revoked honeytoken whose on-disk artifact should be removed; `token` holds the revoked key so the client can verify the profile actually contains it before removing (never clobbering a foreign profile).
    - `token` object — AWS credentials. For `write`, the key to write; for `delete`, the revoked key to match against the on-disk profile before removing it. Present for both actions.
      - `access_token_id` string
      - `secret_key` string

## Other responses

- `400` — Invalid data
- `401` — Invalid API key
- `403` — Forbidden Call
- `503` — API under maintenance

---

[API](https://skmtc.net/gitguardian/apis/gitguardian-api.md) · [All operations](https://skmtc.net/gitguardian/apis/gitguardian-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gitguardian/gitguardian-api/revisions/511b067cdcb1/schema)