# Create or update org secret

**PUT /api/v1/projects/{id}/secrets/{name}**

Validates the secret name and proxies the upsert request to ECP. Secret values are never returned. The project scope is carried by the route id path parameter and the org is derived from that project. Accepts either a session JWT or a project-scoped API key, so CI/CD can seed short-lived build credentials without an interactive login; an API key must be scoped to the project named in the path. A project secret is shared by every workspace in the project, so writing one requires project-ownership rights: PROJECT_OWNER, ORG_ADMIN on Agent Engine-native projects, or SYSTEM_ADMIN. AGENT_DEVELOPER is not sufficient here — use the workspace-scoped secret endpoint for per-workspace credentials.


## Servers
- https://agentengine.mongodb.com: https://agentengine.mongodb.com ()


## Authentication methods
- Bearer auth


## Parameters

### Path parameters

- **id** (string)
  Project ID

- **name** (string)
  Secret name (uppercase env-var style)



### Body: application/json (object)
Secret value and optional description
- **description** (string)

- **value** (string)

- **value_unchanged** (boolean)
  ValueUnchanged must be explicitly set by a caller editing only the
  description of an existing secret; it is what allows Value to be
  empty. Without it, an empty Value is always rejected - a caller that
  sends "" by mistake (e.g. a templating bug or unset env var) gets a
  clear 400 instead of silently leaving the old value in place.



## Responses
### 406
Unsupported or malformed API version, an operation unavailable in the selected published contract, or an unacceptable representation (including unsupported media-type parameters or excluded SSE). Existing authentication, authorization, and rate-limit failures take precedence.

#### Body: application/json (object)
- **badRequestDetail** (object)
  Optional validation details defined by the standard error schema; API negotiation errors do not emit this field.

- **detail** (string)
  Human-readable error details.

- **error** (integer)
  HTTP status code.

- **errorCode** (string)
  Machine-readable error code.

- **parameters** (array[string])
  Request parameter names associated with the error; omitted when none apply.

- **reason** (string)
  HTTP status reason phrase.


### 200
OK

#### Body: application/json (object)
- **created_at** (string)

- **description** (string)

- **name** (string)

- **updated_at** (string)

- **version** (integer)


### 400
Bad Request

#### Body: application/json (object)
- **code** (string)

- **error** (string)

- **success** (boolean)


### 403
Forbidden

#### Body: application/json (object)
- **code** (string)

- **error** (string)

- **success** (boolean)


### 413
Request Entity Too Large

#### Body: application/json (object)
- **code** (string)

- **error** (string)

- **success** (boolean)


### 429
Too Many Requests
#### Headers

- **Retry-After** (string)
  Seconds to wait before retrying


#### Body: application/json (object)
- **code** (string)

- **error** (string)

- **success** (boolean)


### 502
Bad Gateway

#### Body: application/json (object)
- **code** (string)

- **error** (string)

- **success** (boolean)


### 503
Service Unavailable
#### Headers

- **Retry-After** (string)
  Seconds to wait before retrying


#### Body: application/json (object)
- **code** (string)

- **error** (string)

- **success** (boolean)



[Powered by Bump.sh](https://bump.sh)