openapi: 3.1.0
info:
  title: TensorDock Secrets API
  description: |
    The TensorDock Secrets API (v2) for managing SSH keys and generic secrets
    that can be attached to instances at deploy time. Secrets are encrypted at
    rest and in transit. Two types are supported: `SSHKEY` for SSH access and
    `GENERIC` / `SECRET` for opaque application credentials whose `value` is
    never returned after creation.
  version: '2.0'
  contact:
    name: TensorDock Support
    email: support@tensordock.com
    url: https://marketplace.tensordock.com/support
  x-logo:
    url: https://www.tensordock.com/favicon.ico

servers:
  - url: https://dashboard.tensordock.com
    description: TensorDock Dashboard (production)

security:
  - BearerAuth: []

tags:
  - name: Secrets
    description: Manage SSH keys and generic secrets

paths:
  /api/v2/secrets:
    get:
      summary: List Secrets
      description: List all secrets registered for the calling organization. The `value` of
        `GENERIC` / `SECRET` typed entries is never returned.
      operationId: listSecrets
      tags:
        - Secrets
      responses:
        '200':
          description: Array of secrets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretListResponse'

    post:
      summary: Create Secret
      description: Create a new SSH key or generic secret. The `value` of `GENERIC` / `SECRET`
        typed entries is encrypted at rest and never returned after creation.
      operationId: createSecret
      tags:
        - Secrets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSecretRequest'
      responses:
        '201':
          description: Secret created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretResponse'

  /api/v2/secrets/{id}:
    get:
      summary: Get Secret
      description: Retrieve a secret by ID. For secrets of type `GENERIC` / `SECRET`, the
        `value` field is never returned.
      operationId: getSecret
      tags:
        - Secrets
      parameters:
        - $ref: '#/components/parameters/SecretId'
      responses:
        '200':
          description: Secret details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretResponse'

    delete:
      summary: Delete Secret
      description: Permanently delete a secret.
      operationId: deleteSecret
      tags:
        - Secrets
      parameters:
        - $ref: '#/components/parameters/SecretId'
      responses:
        '200':
          description: Secret deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        const: success
                      message:
                        type: string

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

  parameters:
    SecretId:
      in: path
      name: id
      required: true
      schema:
        type: string

  schemas:
    Secret:
      type: object
      properties:
        type:
          type: string
          const: secret
        id:
          type: string
        attributes:
          type: object
          properties:
            name:
              type: string
            secret_type:
              type: string
              enum: [SSHKEY, GENERIC, SECRET]
            value:
              type: string
              description: Plaintext value for `SSHKEY` only; `GENERIC` / `SECRET` types omit this field.

    SecretListResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            secrets:
              type: array
              items:
                $ref: '#/components/schemas/Secret'

    SecretResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Secret'

    CreateSecretRequest:
      type: object
      required:
        - data
      properties:
        data:
          type: object
          required:
            - type
            - attributes
          properties:
            type:
              type: string
              const: secret
            attributes:
              type: object
              required:
                - name
                - value
                - secret_type
              properties:
                name:
                  type: string
                value:
                  type: string
                secret_type:
                  type: string
                  enum: [SSHKEY, GENERIC, SECRET]