---
title: "Create a honeytoken"
method: POST
path: "/v1/honeytokens"
tags: ["Honeytokens"]
---

# Create a honeytoken

`POST /v1/honeytokens`

This endpoint allows you to create a honeytoken of a type.

If you are using a personal access token, you need to have an access level superior or equal to `manager`.

## Request body

- object
  - `name` string, required — honeytoken name.
  - `description` string — honeytoken description.
  - `type` 'AWS', required — honeytoken type
  - `custom_tags` object[] — Custom tags to set on the honeytoken. If the custom tag doesn't exist, it will be created.
    - `id` string, uuid
    - `key` string
    - `value` string, nullable

## Response `201`

Honeytoken created

- object
  - `id` string, uuid
  - `name` string
  - `description` string
  - `created_at` string, date-time — Creation date of the honeytoken
  - `gitguardian_url` string
  - `status` 'active' | 'triggered' | 'revoked' — Status of the honeytoken.
  - `triggered_at` string, date-time — Date when the honeytoken was switched from active to triggered the last time
  - `revoked_at` string, date-time — Date when the honeytoken was revoked
  - `open_events_count` integer
  - `type` 'AWS' — Type of the honeytoken.
  - `creator_id` integer, nullable — Id of the member who created this honeytoken.
  - `revoker_id` integer, nullable — Id of the member who revoked this honeytoken.
  - `creator_api_token_id` string, uuid, nullable — ID of the API key which created this honeytoken. Can be null if the honeytoken was not created via the API.
  - `revoker_api_token_id` string, uuid, nullable — ID of the API key which created honeytoken note. Can be null if the honeytoken was not created via the API.
  - `token` object — Secret to be placed as a honeytoken.
  - `tags` string[]
  - `custom_tags` object[] — Custom tags set on the honeytoken.
    - `id` string, uuid
    - `key` string
    - `value` string, nullable

## Other responses

- `400` — Invalid data
- `401` — Invalid API key
- `403` — Forbidden Call
- `409` — Data conflict
- `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)