openapi: 3.0.0
info:
  description: >-
    This document specifies the **Keystore related operations RESTful API** for
    **WSO2 Identity Server**
  version: v1
  title: Keystore API
servers:
  - url: https://{serverUrl}/t/{tenantDomain}/api/server/v1
    variables:
      serverUrl:
        default: localhost:9443
      tenantDomain:
        default: carbon.super
paths:
  /keystores/certs:
    get:
      tags:
        - Certificates
      summary: Retrieve the list of certificate aliases
      operationId: getCertificateAliases
      description: >
        This REST API can be used to get the certificate aliases from the
        keystore


        <b>Scope(Permission) required:</b> `internal_keystore_view`
      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'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'GET' \
            'https://localhost:9443/api/server/v1/keystores/certs' \
            -H 'accept: application/json' \
            -H 'Authorization: Basic YWRtaW46YWRtaW4='
    post:
      tags:
        - Certificates
      summary: Upload 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.


        <b>Scope(Permission) required:</b> `internal_keystore_update`
      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'
      x-codeSamples:
        - lang: Curl
          source: >
            curl -X 'POST' \

            'https://localhost:9443/api/server/v1/keystores/certs' \

            -H 'accept: */*' \

            -H 'Authorization: Basic YWRtaW46YWRtaW4=' \

            -H 'Content-Type: application/json' \

            -d '{

            "alias": "newcert",

            "certificate":
            "MIIDADCCAeigAwIBAgIEnRKL8zANBgkqhkiG9w0BAQQFADBCMREwDwYDVQQDDAh3c28yLmNvbTENMAsGA1UECwwETm9uZTEPMA0GA1UECgwGTm9uZSBMMQ0wCwYDVQQGEwROb25lMB4XDTE5MDkyMjA5MzgyM1oXDTI5MTAxOTA5MzgyM1owQjERMA8GA1UEAwwId3NvMi5jb20xDTALBgNVBAsMBE5vbmUxDzANBgNVBAoMBk5vbmUgTDENMAsGA1UEBhMETm9uZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMY6diX4CyRNARLYQq5tLnjSMbCh4waM7EDniKeZuQAKVdBpzgvan+G8QrgfJqZ7IfYCLFKSQIpblMiULnaf0Zy1VqQG+QNh+CHpMJ0jRPAKWUXQrgzFu24+araRei9v9VBHVwaNVp1uHKx9cL4XAXdIRv+ZDCTrkvJJUPxrNgF14UIUPsNIZF5perptTUUaudyDiGug80baTXxuEf7gJh6LcT5UIJF/moWKhLYhKEFa7nq7sJLcGIUKRlIxF487rTe1zZzN9RsdpH5d11DnltThOdO1mF9BX1U6F3yuJoOlsIcHIeab0XED0jw8PFi5+LT7EOe6xzaB9sL2DB38o8sCAwEAATANBgkqhkiG9w0BAQQFAAOCAQEArqGJfCOIjY5sFhO6Fd5x3dM6OrA7QcjxzNxsNwO7e2zFr4SHJqekfErZxFTLGWMpyMakvTFAk3e/ShvDQ71nBxYl6Rbdco0f2SUI2ig3lQR5ZTxPmxSSNNbX4K2ptAgzikmSjc6lrGRUnMkMKetClDRsOf9banuDImB2aIn2STmFR2U5duui2oEep3C5mlxregBXI8xEWF6VpXzeEz2AEOaKWOPLDTQsBWxSFi9uVVkD9GwN7yJCXWF81enCpQ4U1PHVhAdS40HTXbis/R0+ykDdkDLmbu3Oa+F2uyWnarAR9rKVfjNovXvJPX4D+5/wipDyXUOO58tyF0342JuIdA=="

            }'
  /keystores/certs/public:
    get:
      tags:
        - Certificates
      summary: Retrieve the public certificate
      operationId: getPublicCertificate
      description: >
        This REST API can be used to download the public certificate from the
        keystore.<br>


        <b>Scope(Permission) required:</b> None
      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'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'GET' \
            'https://localhost:9443/api/server/v1/keystores/certs/public' \
            -H 'accept: application/pkix-cert'
  /keystores/certs/{alias}:
    get:
      tags:
        - Certificates
      summary: Retrieve the certificate of the provided alias
      operationId: getCertificate
      description: >
        This REST API can be used to download the certificate from the
        keystore<br>


        <b>Scope(Permission) required:</b> `internal_keystore_view`
      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'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'GET' \
            'https://localhost:9443/api/server/v1/keystores/certs/{alias}' \
            -H 'accept: application/pkix-cert' \
            -H 'Authorization: Basic YWRtaW46YWRtaW4='
    delete:
      tags:
        - Certificates
      summary: Delete 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.<br>


        <b>Scope(Permission) required:</b> `internal_keystore_update`
      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'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'DELETE' \
            'https://localhost:9443/api/server/v1/keystores/certs/{alias}' \
            -H 'accept: */*' \
            -H 'Authorization: Basic YWRtaW46YWRtaW4='
  /keystores/client-certs:
    get:
      tags:
        - Certificates
      summary: Retrieve 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<br>


        <b>Scope(Permission) required:</b> `internal_keystore_view`
      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'
      x-codeSamples:
        - lang: Curl
          source: |
            curl -X 'GET' \
            'https://localhost:9443/api/server/v1/keystores/client-certs' \
            -H 'accept: application/json' \
            -H 'Authorization: Basic YWRtaW46YWRtaW4='
  /keystores/client-certs/{alias}:
    get:
      tags:
        - Certificates
      summary: Retrieve 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<br>


        <b>Scope(Permission) required:</b> `internal_keystore_view`
      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'
      x-codeSamples:
        - lang: Curl
          source: >
            curl -X 'GET' \

            'https://localhost:9443/api/server/v1/keystores/client-certs/{alias}'
            \

            -H 'accept: application/pkix-cert' \

            -H 'Authorization: Basic YWRtaW46YWRtaW4='
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/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
