openapi: 3.2.0
info:
  title: Webscale Secrets API
  version: '2026.273'
  description: The Webscale APIs allow programmatic access to the Webscale services.
servers:
- url: https://api.webscale.com/v2
security:
- access_key: []
tags:
- name: Secrets
  x-tag-expanded: false
paths:
  /secrets:
    get:
      summary: Read secret collection
      description: Will return all the secret resources that the caller is authorized to view.
      tags:
      - Secrets
      responses:
        '200':
          description: The call was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretArray'
      operationId: getSecrets
      x-operation-id-source: derived
    post:
      summary: Create a secret
      description: ''
      parameters: []
      tags:
      - Secrets
      responses:
        '200':
          description: The secret was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretPost'
              description: The secret definition.
      operationId: postSecrets
      x-operation-id-source: derived
  /secrets/{id}:
    get:
      summary: Read a secret
      description: Read metadata about a secret. Secret content is not available.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Secret id.
      tags:
      - Secrets
      responses:
        '200':
          description: The call was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
      operationId: getSecretsById
      x-operation-id-source: derived
    delete:
      summary: Delete a secret
      description: Secrets referenced by resources cannot be deleted.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Secret id.
      tags:
      - Secrets
      responses:
        '200':
          description: The call was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
      operationId: deleteSecretsById
      x-operation-id-source: derived
components:
  schemas:
    SecretContent:
      type: string
      description: The contents of the secret.
    SecretDescription:
      type: string
      description: Description of the resource.
    SecretMimeType:
      type: string
      description: The mime_type of the secret format.
      enum:
      - application/x-hotp-secret
      - application/x-pem-file
      - application/json
      - application/openssh-private-key
    SecretArray:
      type: array
      items:
        $ref: '#/components/schemas/Secret'
    SecretHref:
      type: string
      pattern: ^/v2/secrets/[a-z0-9]+$
      description: The endpoint for the secret resource.
    Secret:
      type: object
      required:
      - description
      - href
      - mime_type
      properties:
        description:
          $ref: '#/components/schemas/SecretDescription'
        href:
          $ref: '#/components/schemas/SecretHref'
        mime_type:
          $ref: '#/components/schemas/SecretMimeType'
        personal:
          type: boolean
          description: If true, the secret will be associated with the user making the request
      additionalProperties: false
    SecretPost:
      required:
      - content
      - mime_type
      properties:
        content:
          $ref: '#/components/schemas/SecretContent'
        description:
          $ref: '#/components/schemas/SecretDescription'
        mime_type:
          $ref: '#/components/schemas/SecretMimeType'
        personal:
          type: boolean
          description: If true, the secret will be associated with the user making the request
      additionalProperties: false
  securitySchemes:
    access_key:
      type: http
      scheme: Bearer
      description: "An access key secret must be sent as a\n[bearer token](https://www.rfc-editor.org/rfc/rfc7235#section-5.1)\nwith each HTTP request in an `Authorization` header.  Tokens are obtained\nin one of three ways:\n\n1. Creating an access key in your\n   [user profile](https://control.webscale.com/profile).\n2. Using an access key secret created when a service user is created\n   with the [POST accounts/{id}/service-users](#post-/accounts/-id-/service-users)\n   API.\n3. Obtaining a temporary access key using an existing access key secret\n   for a specified account with the\n   [POST users/self/authorization](#post-/users/-id-/authorization) API.\n"