---
title: "Create a Secret"
method: POST
path: "/v1/secrets"
---

# Create a Secret

`POST /v1/secrets`

## Request

- Base URL: `https://api.browserbase.com`
- URL: `https://api.browserbase.com/v1/secrets`
- Auth: API key in header `X-BB-API-Key`

## Request body

- object
  - `secretKey` string, required: The name to store the secret value under.
  - `sealedSecretValue` string, required: The secret value encrypted with HPKE. To seal the secret value before sending, get the project's public key from GET /v1/secrets/keypair. Decode the publicKey using base64 into the raw 32-byte public key. Then, use HPKE Base mode (RFC 9180) with the following algorithm suite: DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, and AES-256-GCM. Set both info and additional authenticated data (AAD) to an empty byte string. Then, create a new sender context using the public key and these settings, and encrypt the secret value as one message. Put the 32-byte encapsulated key before the ciphertext and keep the authentication tag at the end of the ciphertext. Encode the combined bytes with standard base64. Send the result as sealedSecretValue: base64(enc || ciphertext)
  - `keypairId` string, required: The `id` returned by GET /v1/secrets/keypair, identifying the keypair whose public key encrypted the value. Recorded with the secret so decryption stays correct across keypair rotation.

## Response `201`

The request has succeeded and a new resource was created.

- Secret
  - `id` string, required: Unique identifier of the secret.
  - `secretKey` string, required: The name the secret value is stored under.
  - `createdAt` string, date-time: Time at which the secret was created, in UTC, using RFC 3339 format, e.g. 2026-01-19T00:00:00.000Z.
  - `updatedAt` string, date-time: Time at which the secret's value was last set, in UTC, using RFC 3339 format, e.g. 2026-01-20T00:00:00.000Z.

## Other responses

- `400`: Invalid request, or keypairId does not identify an active keypair in the project. If the keypair is no longer active, fetch GET /v1/secrets/keypair, seal the value again, and retry.
- `409`: A secret with this name already exists in the project.

## Changes

- **2026-10-30** `3661c37195a7`: 2 info
  - added the optional property `createdAt` to the response with the `201` status
  - added the optional property `updatedAt` to the response with the `201` status
- **2026-10-16** `266d5199a560`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/browserbase/apis/browserbase-api/changes/v1/secrets/post.md)

---

[API](https://skmtc.dev/browserbase/apis/browserbase-api.md) - [All operations](https://skmtc.dev/browserbase/apis/browserbase-api/llms.txt) - [OpenAPI document](https://skmtc.dev/browserbase/apis/browserbase-api/revisions/106c5f72c742?raw)