Create or update org secret

PUT /api/v1/projects/{id}/secrets/{name}
Bearer auth

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.

Path parameters

  • id string Required

    Project ID

  • name string Required

    Secret name (uppercase env-var style)

application/json

Body Required

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.

    Hide response attributes Show response attributes object
    • badRequestDetail object

      Optional validation details defined by the standard error schema; API negotiation errors do not emit this field.

      Hide badRequestDetail attribute Show badRequestDetail attribute object
      • fields array[object]

        Fields with validation failures.

        Hide fields attributes Show fields attributes object

        A field and its validation failure.

        • description string Required

          Human-readable validation failure.

        • field string Required

          Name or path of the invalid request field.

    • detail string Required

      Human-readable error details.

    • error integer Required

      HTTP status code.

    • errorCode string Required

      Machine-readable error code.

    • parameters array[string]

      Request parameter names associated with the error; omitted when none apply.

    • reason string Required

      HTTP status reason phrase.

    Hide response attributes Show response attributes object
    • badRequestDetail object

      Optional validation details defined by the standard error schema; API negotiation errors do not emit this field.

      Hide badRequestDetail attribute Show badRequestDetail attribute object
      • fields array[object]

        Fields with validation failures.

        Hide fields attributes Show fields attributes object

        A field and its validation failure.

        • description string Required

          Human-readable validation failure.

        • field string Required

          Name or path of the invalid request field.

    • detail string Required

      Human-readable error details.

    • error integer Required

      HTTP status code.

    • errorCode string Required

      Machine-readable error code.

    • parameters array[string]

      Request parameter names associated with the error; omitted when none apply.

    • reason string Required

      HTTP status reason phrase.
  • 200

    OK

    Hide response attributes Show response attributes object
    • created_at string
    • description string
    • name string
    • updated_at string
    • version integer
    Hide response attributes Show response attributes object
    • created_at string
    • description string
    • name string
    • updated_at string
    • version integer
  • 400

    Bad Request

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 403

    Forbidden

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 413

    Request Entity Too Large

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 429

    Too Many Requests

    Hide headers attribute Show headers attribute
    • Retry-After string

      Seconds to wait before retrying

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 502

    Bad Gateway

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
  • 503

    Service Unavailable

    Hide headers attribute Show headers attribute
    • Retry-After string

      Seconds to wait before retrying

    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
    Hide response attributes Show response attributes object
    • code string
    • error string
    • success boolean
PUT /api/v1/projects/{id}/secrets/{name} 
curl \
 --request PUT 'https://agentengine.mongodb.com/api/v1/projects/{id}/secrets/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
  "description": "string",
  "value": "string",
  "value_unchanged": true
}'
Request examples 
{
  "description": "string",
  "value": "string",
  "value_unchanged": true
}
Response examples (406) 
{
  "detail": "This operation is not available in API version 2026-09-20-preview.",
  "error": 406,
  "errorCode": "OPERATION_NOT_IN_API_VERSION",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}
{
  "detail": "This operation supports text/event-stream, which the Accept header excludes. Remove unsupported media-type parameters or accept this type with a positive q value.",
  "error": 406,
  "errorCode": "UNACCEPTABLE_MEDIA_TYPE",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}
{
  "detail": "The requested API version is not supported. Supported versions: 2026-09-20-preview.",
  "error": 406,
  "errorCode": "UNSUPPORTED_API_VERSION",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}
Response examples (406) 
{
  "detail": "This operation is not available in API version 2026-09-20-preview.",
  "error": 406,
  "errorCode": "OPERATION_NOT_IN_API_VERSION",
  "parameters": [
    "Accept"
  ],
  "reason": "Not Acceptable"
}
Response examples (200) 
{
  "created_at": "string",
  "description": "string",
  "name": "string",
  "updated_at": "string",
  "version": 42
}
Response examples (200) 
{
  "created_at": "string",
  "description": "string",
  "name": "string",
  "updated_at": "string",
  "version": 42
}
Response examples (400) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (400) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (403) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (403) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (413) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (413) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (429) 
# Headers
Retry-After: string

# Payload
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (429) 
# Headers
Retry-After: string

# Payload
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (502) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (502) 
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (503) 
# Headers
Retry-After: string

# Payload
{
  "code": "string",
  "error": "string",
  "success": true
}
Response examples (503) 
# Headers
Retry-After: string

# Payload
{
  "code": "string",
  "error": "string",
  "success": true
}