openapi: 3.1.0
info:
  title: Soda Cloud REST Attributes Secrets API
  description: The Soda Cloud REST API enables programmatic access to trigger data quality scans, retrieve check results, update incident status, manage datasets, datasources, contracts, runners, secrets, notification rules, and integrate data quality workflows into CI/CD pipelines. Supports EU and US cloud regions.
  version: 1.0.0
  contact:
    name: Soda Support
    url: https://soda.io
servers:
- url: https://cloud.soda.io
  description: EU Cloud
- url: https://cloud.us.soda.io
  description: US Cloud
security:
- basicAuth: []
tags:
- name: Secrets
  description: Encrypted secret storage for datasource credentials
paths:
  /api/v1/secrets:
    get:
      summary: List secrets
      description: Requires MANAGE_DATASOURCES_AND_AGENTS permission.
      operationId: listSecrets
      tags:
      - Secrets
      parameters:
      - name: size
        in: query
        schema:
          type: integer
          minimum: 10
          maximum: 1000
          default: 10
      - name: page
        in: query
        schema:
          type: integer
          default: 0
      - name: search
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Paginated list of secrets
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      summary: Create secret
      operationId: createSecret
      tags:
      - Secrets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSecretRequest'
      responses:
        '200':
          description: Secret created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/secrets/{secretId}:
    post:
      summary: Update secret
      operationId: updateSecret
      tags:
      - Secrets
      parameters:
      - name: secretId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSecretRequest'
      responses:
        '200':
          description: Secret updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      summary: Delete secret
      operationId: deleteSecret
      tags:
      - Secrets
      parameters:
      - name: secretId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Secret deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v1/secretsPublicKey:
    get:
      summary: Get encryption public key
      description: Retrieve the JWK format public key for encrypting secrets.
      operationId: getSecretsPublicKey
      tags:
      - Secrets
      responses:
        '200':
          description: JWK format public key
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    UpdateSecretRequest:
      type: object
      required:
      - encryptedValue
      - encryptionKey
      properties:
        encryptedValue:
          type: string
        encryptionKey:
          type: string
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    CreateSecretRequest:
      type: object
      required:
      - name
      - encryptedValue
      - encryptionKey
      properties:
        name:
          type: string
          pattern: ^\S+$
          description: Secret name, no whitespace
        encryptedValue:
          type: string
        encryptionKey:
          type: string
  responses:
    Unauthorized:
      description: Unauthorized - authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Base64-encoded API key ID and secret: base64(api_key_id:api_key_secret)'