---
title: "Create secret"
method: POST
path: "/secrets"
tags: ["Forward"]
---

# Create secret

`POST /secrets`

## Request

- Base URL: `https://forward.checkout.com`
- URL: `https://forward.checkout.com/secrets`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `string` scopes: `forward`, `forward:secrets`
  - API key in header `Authorization`
- TypeScript: <https://skmtc.dev/checkout/apis/checkout-com-api-reference/docs/secrets/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Request body

- CreateSecretPlaintextRequest: Request to create a secret with plaintext value
  - `name` string, required: Secret name. <br/> Format – 1-64 characters. Alphanumeric and underscore.
  - `value` string, required: Plaintext secret value. Max 8KB.
  - `entity_id` string: Optional.When provided, the secret is scoped to this entity

## Response `201`

Secret created successfully.

- SecretResponse: Secret response metadata. The secret value is never returned in responses.
  - `name` string, required: Secret name (1-64 characters, alphanumeric and underscore)
  - `created_at` string, date-time, required: Timestamp when the secret was created.
  - `updated_at` string, date-time, required: Timestamp when the secret was last updated.
  - `version` integer, required: Version number.
  - `entity_id` string: Entity ID if the secret is scoped to a specific entity.

## Other responses

- `401`: Unauthorized
- `409`: Conflict - secret with this name already exists
- `422`: Invalid data was sent
- `500`: Internal Error

---

[API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)