Create secret

​

Create a new secret with a plaintext value.

Validation Rules:

  • name: 1-64 characters, alphanumeric + underscore
  • value: max 8KB
  • entity_id (optional): when provided, secret is scoped to this entity

Response: Returns metadata.

Body·
required
application/json

Request to create a secret with plaintext value

  • name
    Type: string
    min length:  
    1
    max length:  
    64    Pattern: ^[a-zA-Z0-9_]{1,64}$
    required

    Secret name.
    Format – 1-64 characters. Alphanumeric and underscore.

  • value
    Type: string
    max length:  
    8192
    required

    Plaintext secret value. Max 8KB.

  • entity_id
    Type: string

    Optional.When provided, the secret is scoped to this entity

Responses
  • application/json
  • 401

    Unauthorized

  • 409

    Conflict - secret with this name already exists

  • application/json
  • 500

    Internal Error

Request Example for post/secrets
curl https://forward.checkout.com/secrets \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "name": "secret_name",
  "value": "plaintext",
  "entity_id": "ent_12345"
}'

{
  "name": "secret_name",
  "created_at": "2025-10-14T00:00:00Z",
  "updated_at": "2025-10-14T00:00:00Z",
  "version": 1,
  "entity_id": "ent_123"
}

Secret created successfully.