# generated: '2026-08-29'
# method: searched
# source: https://docs.soda.io/reference/soda-apis/rest-api/ — assembled from the OpenAPI 3.1.0
#   documents Soda publishes inline on each REST API reference page (16 pages, 103 operations,
#   zero conflicting definitions). Ownership: info.title 'Soda Cloud API v4', servers
#   https://cloud.soda.io + https://cloud.us.soda.io — Soda's own hosts.
openapi: 3.1.0
info:
  title: Soda Cloud API v4 — Secrets
  version: v1
  description: The Secrets surface of the Soda Cloud v4 public REST API — 5 operation(s). Harvested verbatim
    from the OpenAPI documents Soda publishes at https://docs.soda.io/reference/soda-apis/rest-api/.
  contact:
    name: Soda
    url: https://www.soda.io
servers:
- description: Cloud EU
  url: https://cloud.soda.io
- description: Cloud US
  url: https://cloud.us.soda.io
security:
- basicAuthApiKey: []
- cookieToken: []
tags:
- name: Secrets
  description: Soda Cloud API Secret Endpoints
paths:
  /api/v1/secrets:
    get:
      description: 'This endpoint allows you to list secrets in your organization.


        This GET is a paginated API that uses the following parameters to request specific details:


        - `size`: Supply an integer value between 10 and 1000, inclusive. The default value is 10.


        - `page`: Supply an integer value. The default value is 0.


        - `search`: Supply a string value to filter secrets by name (case-insensitive partial match).


        ## Authentication


        User authentication required: `true`


        This endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated
        token in HTTP cookie `token`. Cookie sessions extend automatically on each request.


        ## Authorization


        Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.


        ## Tags


        `Secrets`


        ## Rate limiting


        60 requests/60 seconds'
      operationId: GET/api/v1/secrets
      parameters:
      - in: query
        name: page
        schema:
          type: integer
          format: int32
      - in: query
        name: search
        schema:
          type: string
      - in: query
        name: size
        schema:
          type: integer
          format: int32
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/PublicApiListSecretsResponse'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: List secrets
      tags:
      - Secrets
    post:
      description: 'Creates a new secret in your organization. Secrets store encrypted credentials that
        can be referenced in datasource configurations using `${secret.NAME}` placeholders, keeping sensitive
        values out of plain text.


        ## Encryption


        Secret values must be encrypted **client-side** before sending them to this endpoint. This enables
        a zero-trust design, where Soda never decrypts the secret. Decryption happens only during scan
        execution, within the runner.


        Use the `GET /api/v1/secretsPublicKey` endpoint to obtain the server''s RSA public key. The encryption
        uses a two-layer scheme:


        1. Fetch the RSA public key from `GET /api/v1/secretsPublicKey`.


        2. Generate a random AES-256-GCM key (32 bytes) and initialization vector (IV, 12 bytes).


        3. Encrypt the secret value using AES-256-GCM with the generated key and IV. Base64-encode the
        ciphertext and prefix it with `encrypted_`. This becomes the `encryptedValue` field.


        4. Export the raw AES key and IV as base64 strings and concatenate them as `{base64_key}:::{base64_iv}`.
        Encrypt this string using RSA-OAEP (SHA-256) with the public key from step 1. Base64-encode the
        result. This becomes the `encryptionKey` field.


        ## Constraints


        - The secret `name` must not contain whitespace and must be unique within the organization.


        - Both `encryptionKey` and `encryptedValue` are required.


        - The organization must have the contracts feature enabled and the secure store must not be disabled.


        ## Authentication


        User authentication required: `true`


        This endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated
        token in HTTP cookie `token`. Cookie sessions extend automatically on each request.


        ## Authorization


        Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.


        ## Tags


        `Secrets`


        ## Rate limiting


        10 requests/60 seconds'
      operationId: POST/api/v1/secrets
      requestBody:
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/PublicApiCreateSecretRequestDTO'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/PublicApiCreateSecretResponse'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Create a secret
      tags:
      - Secrets
  /api/v1/secrets/{secretId}:
    post:
      description: 'Updates the encrypted value of an existing secret. The secret name cannot be changed.


        Both `encryptionKey` and `encryptedValue` must be provided together — you cannot update one without
        the other.


        ## Encryption


        The new secret value must be encrypted **client-side** using the same two-layer encryption scheme
        as creation. See the `POST /api/v1/secrets` (Create a secret) endpoint for the full encryption
        workflow.


        ## Authentication


        User authentication required: `true`


        This endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated
        token in HTTP cookie `token`. Cookie sessions extend automatically on each request.


        ## Authorization


        Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.


        ## Tags


        `Secrets`


        ## Rate limiting


        100 requests/60 seconds'
      operationId: POST/api/v1/secrets/{secretId}
      parameters:
      - in: path
        name: secretId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              $ref: '#/components/schemas/PublicApiUpdateSecretRequestDTO'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/PublicApiUpdateSecretResponse'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Update a secret
      tags:
      - Secrets
    delete:
      description: 'Deletes an existing secret.


        The secret cannot be deleted if it is referenced by a datasource configuration.


        ## Authentication


        User authentication required: `true`


        This endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated
        token in HTTP cookie `token`. Cookie sessions extend automatically on each request.


        ## Authorization


        Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.


        ## Tags


        `Secrets`


        ## Rate limiting


        10 requests/60 seconds'
      operationId: DELETE/api/v1/secrets/{secretId}
      parameters:
      - in: path
        name: secretId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/PublicApiDeleteSecretResponse'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '429':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Delete a secret
      tags:
      - Secrets
  /api/v1/secretsPublicKey:
    get:
      description: 'Returns the RSA public key in JWK (JSON Web Key) format, used for client-side encryption
        of secret values.


        ## Usage


        When creating or updating a secret, the secret value must be encrypted client-side before sending
        it to the API. This endpoint provides the RSA public key needed for that encryption.


        ## Encryption workflow


        1. Fetch this public key.


        2. Generate a random AES-256-GCM key (32 bytes) and initialization vector (IV, 12 bytes).


        3. Encrypt the secret value using AES-256-GCM with the generated key and IV. Base64-encode the
        ciphertext and prefix it with `encrypted_`. This becomes the `encryptedValue` field.


        4. Export the raw AES key and IV as base64 strings and concatenate them as `{base64_key}:::{base64_iv}`.
        Encrypt this string using RSA-OAEP (SHA-256) with this public key. Base64-encode the result. This
        becomes the `encryptionKey` field.


        5. Use the `encryptedValue` and `encryptionKey` in the create or update secret request.


        ## Authentication


        User authentication required: `true`


        This endpoint accepts authentication via API keys in the `Basic` authentication header, or a pre-authenticated
        token in HTTP cookie `token`. Cookie sessions extend automatically on each request.


        ## Authorization


        Users must have global role permission MANAGE_DATASOURCES_AND_AGENTS to execute this call.


        ## Tags


        `Secrets`


        ## Rate limiting


        60 requests/60 seconds'
      operationId: GET/api/v1/secretsPublicKey
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/PublicApiGetEncryptionKeyResponse'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Forbidden
        '429':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Too many requests
        '500':
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      summary: Get the encryption public key
      tags:
      - Secrets
components:
  securitySchemes:
    basicAuthApiKey:
      scheme: basic
      type: http
    cookieToken:
      in: cookie
      name: token
      type: apiKey
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    MapOfStringTo_object:
      type: object
      additionalProperties: true
    PublicApiCreateSecretRequestDTO:
      type: object
      properties:
        encryptedValue:
          type: string
        encryptionKey:
          type: string
        name:
          type: string
      required:
      - encryptedValue
      - encryptionKey
      - name
    PublicApiCreateSecretResponse:
      type: object
      properties:
        secret:
          type: object
          $ref: '#/components/schemas/PublicApiSecretDTO'
    PublicApiDeleteSecretResponse:
      type: object
      properties:
        message:
          type: string
    PublicApiGetEncryptionKeyResponse:
      type: object
      properties:
        encryptionKey:
          type: object
          $ref: '#/components/schemas/MapOfStringTo_object'
    PublicApiListSecretsResponse:
      type: object
      properties:
        content:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/PublicApiSecretDTO'
        first:
          type: boolean
        last:
          type: boolean
        number:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
      required:
      - content
      - first
      - last
      - number
      - size
      - totalElements
      - totalPages
    PublicApiSecretDTO:
      type: object
      properties:
        created:
          type: string
          format: date-time
        id:
          type: string
        lastUpdated:
          type: string
          format: date-time
        name:
          type: string
    PublicApiUpdateSecretRequestDTO:
      type: object
      properties:
        encryptedValue:
          type: string
        encryptionKey:
          type: string
      required:
      - encryptedValue
      - encryptionKey
    PublicApiUpdateSecretResponse:
      type: object
      properties:
        secret:
          type: object
          $ref: '#/components/schemas/PublicApiSecretDTO'