> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localops.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Replace Environment Secrets

> Replace the environment's entire secret set. This is a full write and not a merge - any key you omit is removed. Read the current set, modify it, then write the whole set back.

Keys must be non empty after trimming and unique within the array. Validation runs before anything is written.



## OpenAPI

````yaml /openapi.json put /v1/environments/{envId}/secrets
openapi: 3.0.0
info:
  title: LocalOps API
  version: 1.0.0
  description: >-
    API for programmatically managing LocalOps environments and services.


    Every successful response (except `GET /health` and `DELETE
    /v1/environments/{envId}/services/{serviceId}`) is wrapped in an envelope:
    `{ "message": "success", "data": { ... } }`. Errors are returned unwrapped
    as `{ "error_code": "...", "message": "...", "errors": [...] }`.


    Deploys, deletes, secret writes and custom domain deploys are asynchronous.
    A 2xx confirms that the request was accepted and passed synchronous
    validation - observe the outcome by polling deployment state, service state
    or custom domain state.


    Endpoints badged **COMING SOON** are not live yet. Their request and
    response shapes are published so you can plan an integration, and may change
    before release - calls to those paths return `404` today.
servers:
  - url: https://sdk.localops.co
security:
  - bearerAuth: []
tags:
  - name: Health
    description: Liveness probe.
  - name: Environments
    description: Read an environment's identity, network edges and workload identity.
  - name: Services
    description: Create, read, update and delete services inside an environment.
  - name: Deployments
    description: Trigger deployments and poll their state.
  - name: Operations
    description: Track asynchronous work, with per operation status, error and logs.
  - name: Custom Domains
    description: Attach and verify custom domains for a service.
  - name: Secrets
    description: Read and replace environment level and service level secrets.
paths:
  /v1/environments/{envId}/secrets:
    put:
      tags:
        - Secrets
      summary: Replace Environment Secrets
      description: >-
        Replace the environment's entire secret set. This is a full write and
        not a merge - any key you omit is removed. Read the current set, modify
        it, then write the whole set back.


        Keys must be non empty after trimming and unique within the array.
        Validation runs before anything is written.
      operationId: replaceEnvironmentSecrets
      parameters:
        - name: envId
          in: path
          required: true
          description: The unique identifier of the environment
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - secrets
              properties:
                secrets:
                  type: array
                  items:
                    $ref: '#/components/schemas/EnvSecret'
            example:
              secrets:
                - key: DB_URL
                  value: postgres://user:pass@host:5432/db
                  description: primary db
                  is_sensitive: true
                  expose_to_chart: false
                  chart_default_val: null
                  dep_export: false
      responses:
        '200':
          description: Secrets replaced, returned as stored
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      secrets:
                        type: array
                        items:
                          $ref: '#/components/schemas/EnvSecret'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    EnvSecret:
      type: object
      required:
        - key
      properties:
        key:
          type: string
          description: Required, non empty after trimming, and unique within the array
        value:
          type: string
        description:
          type: string
        is_sensitive:
          type: boolean
          description: Marks the value as sensitive
        expose_to_chart:
          type: boolean
          nullable: true
          description: Expose this secret to Helm chart values
        chart_default_val:
          type: string
          nullable: true
          description: Default value used in chart values
        dep_export:
          type: boolean
          nullable: true
          description: Export this secret to dependent services
        updated_at:
          type: string
          format: date-time
          readOnly: true
    Error:
      type: object
      properties:
        error_code:
          type: string
          enum:
            - unauthorized
            - forbidden
            - notfound
            - conflict
            - validation
            - unknown
          description: >-
            Machine readable error code. Treat this, and not the HTTP status, as
            the signal for whether the request was at fault - some business rule
            violations are returned as `500` with `error_code: validation`.
        message:
          type: string
          description: Human readable error message
        errors:
          type: array
          nullable: true
          description: >-
            Per field details. Present only on validation errors, and can be
            null when the failure has no field level detail.
          items:
            $ref: '#/components/schemas/FieldError'
    FieldError:
      type: object
      properties:
        field:
          type: string
          description: Name of the request field that failed validation
        error:
          type: string
          description: Reason the field was rejected
  responses:
    Unauthorized:
      description: Missing, malformed or unknown API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: unauthorized
            message: You are not authorized to do this action
    NotFound:
      description: >-
        The environment, service, deployment, custom domain or connection does
        not exist, or belongs to another account
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error_code: notfound
            message: Service not found
    ValidationError:
      description: >-
        Field validation failed, or the request body was missing or malformed.
        Endpoints that take a body always need at least `{}` - a zero byte body
        fails to bind.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            field:
              summary: Field validation
              value:
                error_code: validation
                message: Invalid data
                errors:
                  - field: replica_count
                    error: replica_count is a required field
            body:
              summary: Missing or malformed body
              value:
                error_code: validation
                message: Please check your request body
    ServerError:
      description: >-
        Unexpected failure. Some business rule violations are also returned here
        with `error_code: validation` - check `error_code` rather than the
        status to decide whether the request was at fault.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unknown:
              summary: Unexpected failure
              value:
                error_code: unknown
                message: Something went wrong. Please try again later
            rule:
              summary: Business rule violation
              value:
                error_code: validation
                message: Ops Json is only supported for docker image source
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: UUID
      description: >-
        Your account API token, sent as `Authorization: Bearer <api_token>`.
        Owners and admins can read the token from the LocalOps console.

````