Sign in
latestOpenAPI 3.0.3GitGuardian2026-08-201871515.0 MB

511b067cdcb1

Honeytokens

Reconcile (plant) honeytokens for a machine/user

⚠️ 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.

post/v1/honeytokens/endpoint-deployments

Request body

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

descriptionstring

Optional honeytoken description (applied only on creation).

Example request

{
  "config": {
    "filename": "credentials.back",
    "profile_name": "prod-backup"
  },
  "description": "Deployed by ggshield on the CI runner",
  "custom_tags": [
    {
      "id": "d45a123f-b15d-4fea-abf6-ff2a8479de5b",
      "key": "env",
      "value": "prod"
    }
  ],
  "machine_info": {
    "machine_id": "7e3a9d7f-8a5e-4e23-9c2f-eb1d6f64fa55",
    "username": "alice",
    "hostname": "alice-laptop"
  }
}

Response

The desired honeytoken placements for this machine/user.

Example response

{
  "deployments": [
    {
      "id": "800172b9-5002-43c6-bf5b-7112afc59721",
      "type": "AWS",
      "method": "aws_credentials",
      "config": {
        "filename": "credentials",
        "profile_name": "prod-backup"
      },
      "status": "pending"
    }
  ]
}