---
title: "Reconcile (plant) honeytokens for a machine/user"
method: POST
path: "/v1/honeytokens/endpoint-deployments"
tags: ["Honeytokens"]
---

# Reconcile (plant) honeytokens for a machine/user

`POST /v1/honeytokens/endpoint-deployments`

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

Reconciles the endpoint honeytokens for a machine and OS user, and returns the
desired on-disk state.

Intended for fleet dissemination (endpoint workers, CI, `ggshield`): the call is
idempotent and safe to retry. It ensures the active honeytoken for the given
`type` exists for `(machine, user)` — minting one (server-generated name) on first
sight, or reusing the existing one — and returns the **full list of that user's
deployments**. Each entry carries an `action`:

- `write` — the honeytoken should be present on disk; `token` holds the AWS
  credentials so the client can write or re-verify the file.
- `delete` — the honeytoken has been revoked (rotation); the client should remove
  the stale on-disk artifact. `token` carries the revoked key so the client can
  verify the on-disk profile is the decoy before removing it.

Each entry carries a sibling `method` plus a `config` payload (`filename`,
`profile_name`). GitGuardian stores only the basename (`filename`); the client
composes the on-disk path from the `method` and the OS (e.g. `~/.aws/credentials`
for an AWS honeytoken). The honeytoken is attached to an upserted Endpoint +
EndpointUser keyed by `(account, machine_id)` and `(endpoint, username)`. Report the
on-disk outcome afterwards via `PATCH /honeytokens/endpoint-deployments/{id}`.

Authorize with the `honeytokens:write` scope.

## Request body

- object
  - `type` 'aws' — Honeytoken kind to reconcile. Optional, defaults to `aws`.
  - `method` 'aws_credentials' | 'aws_config_profile' — Placement method. Optional; defaults to the type's default (`aws_credentials`). Selects how the honeytoken is materialized on the endpoint. `method` + `config` only steer the creation of a *new* deployment for the `(machine, user, type, method)` key — they are ignored if a live deployment already exists (except that a conflicting explicit `config` is rejected, see 409).
  - `config` object — Optional per-call override of the placement config. Omitted fields fall back to the method default. `method` is never accepted here (use the top-level `method`).
    - `filename` string — Basename override (e.g. a less-disruptive `credentials.back`). Safe charset only (`[A-Za-z0-9._-]+`), no `/` and no path traversal — the file always lands in the method's directory.
    - `profile_name` string — Profile/section name override (same safe charset).
  - `description` string — Optional honeytoken description (applied only on creation).
  - `custom_tags` object[] — Custom tags to set on the honeytoken (applied only on creation).
    - `id` string, uuid
    - `key` string
    - `value` string, nullable
  - `machine_info` object, required — Machine and OS user the honeytokens are disseminated to. Used to upsert an Endpoint + EndpointUser keyed by `(account, machine_id)` and `(endpoint, username)` respectively.
    - `machine_id` string, required — Stable machine identifier (key for the Endpoint).
    - `username` string, required — OS-level username on the machine (key for the EndpointUser).
    - `hostname` string, required — Display hostname for the Endpoint.

## Response `200`

The desired honeytoken placements for this machine/user.

- 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
- `409` — The request carried an explicit `config` that conflicts with an already-active deployment for the same `(machine, user, method)`. Revoke it before changing the config.
- `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)