---
title: "Create or replace org_secret"
method: PUT
path: "/v1/org_secret"
tags: ["OrgSecrets"]
---

# Create or replace org_secret

`PUT /v1/org_secret`

Create or replace org_secret. If there is an existing org_secret with the same name as the one specified in the request, will replace the existing org_secret with the provided fields

## Request body

- object
  - `name` string, required — Name of the org secret
  - `type` string, nullable
  - `metadata` object, nullable
  - `secret` string, nullable — Secret value. If omitted in a PUT request, the existing secret value will be left intact, not replaced with null.
  - `org_name` string, nullable — For nearly all users, this parameter should be unnecessary. But in the rare case that your API key belongs to multiple organizations, you may specify the name of the organization the Org Secret belongs in.

## Response `200`

Returns the new org_secret object

- OrgSecret
  - `id` string, uuid, required — Unique identifier for the org secret
  - `created` string, date-time, nullable — Date of org secret creation
  - `org_id` string, uuid, required — Unique identifier for the organization
  - `name` string, required — Name of the org secret
  - `type` string, nullable
  - `metadata` object, nullable
  - `preview_secret` string, nullable

## Other responses

- `400` — The request was unacceptable, often due to missing a required parameter
- `401` — No valid API key provided
- `403` — The API key doesn’t have permissions to perform the request
- `429` — Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
- `500` — Something went wrong on Braintrust's end. (These are rare.)

## Changes

- **2024-09-21** `1e677afe2f7b` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/braintrustdata/apis/braintrust-api/changes/v1/org_secret/put.md)

---

[API](https://skmtc.dev/braintrustdata/apis/braintrust-api.md) · [All operations](https://skmtc.dev/braintrustdata/apis/braintrust-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/braintrustdata/braintrust-api/revisions/938d5abfeeda/schema)