openapi: 3.0.0
info:
  title: WSO2 Identity Server - Secret Manager API Definition
  description: This document specifies a **RESTful API** for **WSO2 Identity Server secret management**
  contact:
    name: WSO2
    url: http://wso2.com/products/identity-server/
    email: iam-dev@wso2.org
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: "v1"
servers:
  - url: https://localhost:9443/t/{tenant-domain}/api/server/v1
    variables:
      tenant-domain:
        default: carbon.super
security:
  - OAuth2: []
  - BasicAuth: []
paths:
  "/secret-type":
    post:
      tags:
        - Secret Type
      description: |
        This API is used to create a new secret type.
      summary: |
        Create secret type
      operationId: createSecretType
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretTypeAddRequest'
      responses:
        "201":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretTypeResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "405":
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/secret-type/{name}':
    get:
      tags:
        - Secret Type
      summary: Retrieve secret type by name
      description: |
        This API provides the capability to retrieve a secret type.
      operationId: getSecretType
      parameters:
        - name: name
          in: path
          description: name of the secret Type
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretTypeResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "405":
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
        - Secret Type
      summary: Update a secret type
      description: |
        This API provides the capability to update a secret type by name.
      operationId: updateSecretType
      parameters:
        - name: name
          in: path
          description: name of the secret type
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretTypeUpdateRequest'
        required: true
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretTypeResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "405":
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - Secret Type
      summary: Delete an secret type by name
      description: |
        This API provides the capability to delete a secret by
        name.
      operationId: deleteSecretType
      parameters:
        - name: name
          in: path
          description: name of the secret
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "405":
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /secrets/{secret-type}:
    get:
      tags:
        - Secret
      summary: Get a list of configured secrets
      description: |
        This API provides the capability to retrieve the list of configured secrets.
      operationId: getSecretsList
      parameters:
        - name: secret-type
          in: path
          description: name of the secret type
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretsList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "405":
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - Secret
      summary: Create a secret
      description: |
        This API provides the capability to create a secret
      operationId: createSecret
      parameters:
        - name: secret-type
          in: path
          description: name of the secret type
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/secretAddRequest'

      responses:
        "201":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "405":
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/secrets/{secret-type}/{name}':
    get:
      tags:
        - Secret
      summary: Retrieve secret by name
      description: |
        This API provides the capability to retrieve a secret
      operationId: getSecret
      parameters:
        - name: secret-type
          in: path
          description: name of the secret type
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: name
          in: path
          description: name of the secret
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "405":
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
        - Secret
      summary: Update a secret
      description: |
        This API provides the capability to update a secret name.
      operationId: updateSecret
      parameters:
        - name: secret-type
          in: path
          description: name of the secret type
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: name
          in: path
          description: name of the secret
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretUpdateRequest'

        required: true
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "405":
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
        - Secret
      summary: Patch a secret by name.
      description: >
        This API provides the capability to update a secret using patch request by using its name.
      operationId: patchSecret
      parameters:
        - name: secret-type
          in: path
          description: name of the secret type
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: name
          in: path
          description: name of the secret
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretPatchRequest'

        required: true
      responses:
        "200":
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "405":
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      tags:
        - Secret
      summary: Delete a secret by name
      description: |
        This API provides the capability to delete a secret by
        name.
      operationId: deleteSecret
      parameters:
        - name: secret-type
          in: path
          description: name of the secret type
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: name
          in: path
          description: name of the secret
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "405":
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "500":
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          example: SECRETM-00000
        message:
          type: string
          example: Some Error Message
        description:
          type: string
          example: Some Error Description
        traceId:
          type: string
          example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047
    secretAddRequest:
      required:
        - name
        - value
      type: object
      properties:
        name:
          type: string
          example: sample-secret
        value:
          type: string
          example: sample-value
        description:
          type: string
          example: Some Error Description

    SecretResponse:
      required:
        - secretId
        - secretName
        - lastModified
        - created
        - type
      type: object
      properties:
        secretId:
          type: string
          example: 30103923-923c-485f-a8f9-606398
        secretName:
          type: string
          example: sample-secret
        created:
          type: string
          example: 2021-09-29 10:36:24.976
        lastModified:
          type: string
          example: 2021-09-29 10:36:24.976
        type:
          type: string
          example: adaptive
        description:
          type: string
          example: sample_description

    SecretUpdateRequest:
      required:
        - value
      type: object
      properties:
        value:
          type: string
          example: new-sample-value
        description:
          type: string
          example: sample_description

    SecretPatchRequest:
      required:
        - operation
        - path
      properties:
        operation:
          type: string
          description: The operation to be performed
          enum:
            - ADD
            - REMOVE
            - REPLACE
          example: REPLACE
        path:
          type: string
          description: A JSON-Pointer
          example: /value
        value:
          type: string
          description: The value to be used within the operations
          example: 'dummyValue'

    SecretsList:
      type: array
      items:
        $ref: '#/components/schemas/SecretResponse'

    SecretTypeAddRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string

    SecretTypeResponse:
      type: object
      properties:
        name:
          type: string
        id:
          type: string
        description:
          type: string

    SecretTypeUpdateRequest:
      type: object
      properties:
        description:
          type: string
          example: sample_description

  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://localhost:9443/oauth2/authorize
          tokenUrl: https://localhost:9443/oauth2/token
          scopes: {}
