openapi: 3.0.0
info:
  description: This is the REST API for Keystore related operations in WSO2 Identity Server
  version: "v1"
  title: WSO2 Identity Server - Keystore API
  contact:
    name: WSO2 Identity Server
    url: 'https://wso2.com/identity-and-access-management'
    email: architecture@wso2.org
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
  - url: 'https://localhost:9443/t/{tenant-domain}/api/server/v1'
    variables:
      tenant-domain:
        default: carbon.super
paths:
  /keystores/certs:
    get:
      tags:
        - Certificates
      summary: retrieves the list of certificate aliases
      operationId: getCertificateAliases
      description: This REST API can be used to get the certificate aliases from the keystore
      security:
        - BasicAuth: []
        - OAuth2: []
      parameters:
        - $ref: '#/components/parameters/filterQueryParam'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CertificateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      tags:
        - Certificates
      summary: uploads the certificate with the given alias
      operationId: uploadCertificate
      description: This REST API can be used to upload the certifate to the tenant keystore. This API is not supported for super tenant.
      security:
        - BasicAuth: []
        - OAuth2: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertificateRequest'
      responses:
        '201':
          description: Created.
          headers:
            Location:
              description: Certificate
              schema:
                type: string
                format: uri
                example: https://localhost:9443/t/wso2.com/api/server/v1/keystores/certs/newcert
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
  /keystores/certs/public:
    get:
      tags:
        - Certificates
      summary: retrieves the public certificate
      operationId: getPublicCertificate
      description: This REST API can be used to download the public certificate from the keystore
      security: []
      parameters:
        - $ref: '#/components/parameters/encodeCertQueryParam'
      responses:
        '200':
          description: OK.
          content:
            application/pkix-cert:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /keystores/certs/{alias}:
    get:
      tags:
        - Certificates
      summary: retrieves the certificate of the provided alias
      operationId: getCertificate
      description: This REST API can be used to download the certificate from the keystore
      security:
        - BasicAuth: []
        - OAuth2: []
      parameters:
        - $ref: '#/components/parameters/aliasPathParam'
        - $ref: '#/components/parameters/encodeCertQueryParam'
      responses:
        '200':
          description: OK.
          content:
            application/pkix-cert:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - Certificates
      summary: deletes the certificate
      operationId: deleteCertificate
      description: This REST API can be used to delete the certificate with the given alias from the tenant keystore. This API is not supported for super tenant.
      security:
        - BasicAuth: []
        - OAuth2: []
      parameters:
        - $ref: '#/components/parameters/aliasPathParam'
      responses:
        '204':
          description: Successfully Deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
  /keystores/client-certs:
    get:
      tags:
        - Certificates
      summary: retrieves the list of certificate aliases from the client truststore
      operationId: getClientCertificateAliases
      description: This REST API can be used to get the list of certificate aliases from the client truststore
      security:
        - BasicAuth: []
        - OAuth2: []
      parameters:
        - $ref: '#/components/parameters/filterQueryParam'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CertificateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /keystores/client-certs/{alias}:
    get:
      tags:
        - Certificates
      summary: retrieves the certificate of the provided alias
      operationId: getClientCertificate
      description: This REST API can be used to download the certificate of specified alias from the client-truststore
      security:
        - BasicAuth: []
        - OAuth2: []
      parameters:
        - $ref: '#/components/parameters/aliasPathParam'
        - $ref: '#/components/parameters/encodeCertQueryParam'
      responses:
        '200':
          description: OK.
          content:
            application/pkix-cert:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    filterQueryParam:
      in: query
      name: filter
      required: false
      description: Condition to filter the retrival of records. Supports 'sw', 'co', 'ew' and 'eq' operations.
                  E.g. keystores/certs?filter=alias+eq+wso2carbon
      schema:
        type: string
    aliasPathParam:
      in: path
      name: alias
      required: true
      description: alias of the certificate
      schema:
        type: string
    encodeCertQueryParam:
      in: query
      name: encode-cert
      required: false
      schema:
        type: boolean
  responses:
    BadRequest:
      description: Bad Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized.
    Forbidden:
      description: Resource Forbidden.
    NotFound:
      description: Resource Not Found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    MethodNotAllowed:
      description: Method Not Allowed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://localhost:9443/oauth2/authorize'
          tokenUrl: 'https://localhost:9443/oauth2/token'
          scopes: {}
  schemas:
    CertificateResponse:
      type: object
      required:
        - alias
        - certificate
      properties:
        alias:
          type: string
          example: wso2carbon
        certificate:
          type: string
          format: uri
          example: https://localhost:9443/t/carbon.super/api/server/v1/keystores/certs/wso2carbon
    CertificateRequest:
      type: object
      required:
        - alias
        - certificate
      properties:
        alias:
          type: string
          example: newcert
        certificate:
          type: string
          example: 'MIIDADCCAeigAwIBAgIEnRKL8zANBgkqhkiG9w0BAQQFADBCMREwDwYDVQQDDAh3c28yLmNvbTENMAsGA1UECwwETm9uZTEPMA0GA1UECgwGTm9uZSBMMQ0wCwYDVQQGEwROb25lMB4XDTE5MDkyMjA5MzgyM1oXDTI5MTAxOTA5MzgyM1owQjERMA8GA1UEAwwId3NvMi5jb20xDTALBgNVBAsMBE5vbmUxDzANBgNVBAoMBk5vbmUgTDENMAsGA1UEBhMETm9uZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMY6diX4CyRNARLYQq5tLnjSMbCh4waM7EDniKeZuQAKVdBpzgvan+G8QrgfJqZ7IfYCLFKSQIpblMiULnaf0Zy1VqQG+QNh+CHpMJ0jRPAKWUXQrgzFu24+araRei9v9VBHVwaNVp1uHKx9cL4XAXdIRv+ZDCTrkvJJUPxrNgF14UIUPsNIZF5perptTUUaudyDiGug80baTXxuEf7gJh6LcT5UIJF/moWKhLYhKEFa7nq7sJLcGIUKRlIxF487rTe1zZzN9RsdpH5d11DnltThOdO1mF9BX1U6F3yuJoOlsIcHIeab0XED0jw8PFi5+LT7EOe6xzaB9sL2DB38o8sCAwEAATANBgkqhkiG9w0BAQQFAAOCAQEArqGJfCOIjY5sFhO6Fd5x3dM6OrA7QcjxzNxsNwO7e2zFr4SHJqekfErZxFTLGWMpyMakvTFAk3e/ShvDQ71nBxYl6Rbdco0f2SUI2ig3lQR5ZTxPmxSSNNbX4K2ptAgzikmSjc6lrGRUnMkMKetClDRsOf9banuDImB2aIn2STmFR2U5duui2oEep3C5mlxregBXI8xEWF6VpXzeEz2AEOaKWOPLDTQsBWxSFi9uVVkD9GwN7yJCXWF81enCpQ4U1PHVhAdS40HTXbis/R0+ykDdkDLmbu3Oa+F2uyWnarAR9rKVfjNovXvJPX4D+5/wipDyXUOO58tyF0342JuIdA=='
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: 'AAA-00000'
        message:
          type: string
          example: 'Some Error Message'
        description:
          type: string
          example: 'Some Error Description'
        traceId:
          type: string
          example: 'e0fbcfeb-3617-43c4-8dd0-7b7d38e13047'
