Kong Certificates API

openapi: 3.1.0
info:
  contact:
    email: support@konghq.com
    name: Kong Inc
    url: https://konghq.com
  description: 'OpenAPI 3.0 spec for Kong Gateway''s Admin API.


    You can learn more about Kong Gateway at [developer.konghq.com](https://developer.konghq.com).

    Give Kong a star at the [Kong/kong](https://github.com/kong/kong) repository.'
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  title: Kong Enterprise Admin ACLs Certificates API
  version: 3.14.0
servers:
- description: Default Admin API URL
  url: '{protocol}://{hostname}:{port}{path}'
  variables:
    hostname:
      default: localhost
      description: Hostname for Kong's Admin API
    path:
      default: /
      description: Base path for Kong's Admin API
    port:
      default: '8001'
      description: Port for Kong's Admin API
    protocol:
      default: http
      description: Protocol for requests to Kong's Admin API
      enum:
      - http
      - https
security:
- adminToken: []
tags:
- description: 'A certificate object represents a public certificate, and can be optionally paired with the corresponding private key. These objects are used by Kong Gateway to handle SSL/TLS termination for encrypted requests, or for use as a trusted CA store when validating peer certificate of client/service.

    <br><br>

    Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames.

    <br><br>

    If intermediate certificates are required in addition to the main certificate, they should be concatenated together into one string.

    '
  name: Certificates
paths:
  /{workspace}/certificates:
    post:
      x-speakeasy-entity-operation:
        terraform-datasource: null
        terraform-resource: Certificate#create
      operationId: create-certificate
      summary: Create a new Certificate
      description: Create a new Certificate
      parameters:
      - $ref: '#/components/parameters/Workspace'
      requestBody:
        description: Description of the new Certificate for creation
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Certificate'
      responses:
        '201':
          description: Successfully created Certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certificate'
        '401':
          $ref: '#/components/responses/HTTP401Error'
      tags:
      - Certificates
  /{workspace}/certificates/{CertificateId}:
    parameters:
    - $ref: '#/components/parameters/CertificateId'
    delete:
      x-speakeasy-entity-operation:
        terraform-datasource: null
        terraform-resource: Certificate#delete
      operationId: delete-certificate
      summary: Delete a Certificate
      description: Delete a Certificate
      parameters:
      - $ref: '#/components/parameters/CertificateId'
      - $ref: '#/components/parameters/Workspace'
      responses:
        '204':
          description: Successfully deleted Certificate or the resource didn't exist
        '401':
          $ref: '#/components/responses/HTTP401Error'
      tags:
      - Certificates
    get:
      x-speakeasy-entity-operation:
        terraform-datasource: null
        terraform-resource: Certificate#read
      operationId: get-certificate
      summary: Get a Certificate
      description: Get a Certificate using ID.
      parameters:
      - $ref: '#/components/parameters/Workspace'
      responses:
        '200':
          description: Successfully fetched Certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certificate'
        '401':
          $ref: '#/components/responses/HTTP401Error'
        '404':
          description: Resource does not exist
      tags:
      - Certificates
    put:
      x-speakeasy-entity-operation:
        terraform-datasource: null
        terraform-resource: Certificate#update
      operationId: upsert-certificate
      summary: Upsert a Certificate
      description: Create or Update Certificate using ID.
      parameters:
      - $ref: '#/components/parameters/Workspace'
      requestBody:
        description: Description of the Certificate
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Certificate'
      responses:
        '200':
          description: Successfully upserted Certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certificate'
        '401':
          $ref: '#/components/responses/HTTP401Error'
      tags:
      - Certificates
  /v2/control-planes/{controlPlaneId}/core-entities/certificates:
    parameters:
    - $ref: '#/components/parameters/controlPlaneId'
    get:
      operationId: list-certificate
      summary: List all Certificates
      description: List all Certificates
      parameters:
      - $ref: '#/components/parameters/PaginationSize'
      - $ref: '#/components/parameters/PaginationOffset'
      - $ref: '#/components/parameters/PaginationTagsFilter'
      responses:
        '200':
          description: A successful response listing Certificates
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Certificate_2'
                  next:
                    $ref: '#/components/schemas/PaginationNextResponse'
                  offset:
                    $ref: '#/components/schemas/PaginationOffsetResponse'
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
      tags:
      - Certificates
    post:
      operationId: create-certificate
      summary: Create a new Certificate
      description: Create a new Certificate
      requestBody:
        description: Description of the new Certificate for creation
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Certificate_2'
      responses:
        '201':
          description: Successfully created Certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certificate_2'
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
      tags:
      - Certificates
  /v2/control-planes/{controlPlaneId}/core-entities/certificates/{CertificateId}:
    parameters:
    - $ref: '#/components/parameters/CertificateId_2'
    - $ref: '#/components/parameters/controlPlaneId'
    delete:
      operationId: delete-certificate
      summary: Delete a Certificate
      description: Delete a Certificate
      parameters:
      - $ref: '#/components/parameters/CertificateId_2'
      responses:
        '204':
          description: Successfully deleted Certificate or the resource didn't exist
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
      tags:
      - Certificates
    get:
      operationId: get-certificate
      summary: Get a Certificate
      description: Get a Certificate using ID.
      responses:
        '200':
          description: Successfully fetched Certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certificate_2'
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
        '404':
          description: Resource does not exist
      tags:
      - Certificates
    put:
      operationId: upsert-certificate
      summary: Upsert a Certificate
      description: Create or Update Certificate using ID.
      requestBody:
        description: Description of the Certificate
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Certificate_2'
      responses:
        '200':
          description: Successfully upserted Certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Certificate_2'
        '401':
          $ref: '#/components/responses/HTTP401Error_2'
      tags:
      - Certificates
components:
  responses:
    HTTP401Error_2:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GatewayUnauthorizedError'
    HTTP401Error:
      description: Unauthorized
      content:
        application/json:
          examples:
            DuplicateApiKey:
              summary: Duplicate API key found
              value:
                message: Duplicate API key found
                status: 401
            InvalidAuthCred:
              summary: Invalid authentication credentials
              value:
                message: Unauthorized
                status: 401
            NoAPIKey:
              summary: No API key found
              value:
                message: No API key found in request
                status: 401
          schema:
            $ref: '#/components/schemas/GatewayUnauthorizedError'
  parameters:
    PaginationSize:
      description: Number of resources to be returned.
      in: query
      name: size
      schema:
        type: integer
        default: 100
        maximum: 1000
        minimum: 1
    Workspace:
      description: The name of the workspace
      in: path
      name: workspace
      required: true
      schema:
        type: string
        example: team-payments
        default: default
    CertificateId_2:
      description: ID of the Certificate to lookup
      example: ddf3cdaa-3329-4961-822a-ce6dbd38eff7
      in: path
      name: CertificateId
      required: true
      schema:
        type: string
    PaginationOffset:
      allowEmptyValue: true
      description: Offset from which to return the next set of resources. Use the value of the 'offset' field from the response of a list operation as input here to paginate through all the resources
      in: query
      name: offset
      schema:
        type: string
    CertificateId:
      description: ID of the Certificate to lookup
      example: ddf3cdaa-3329-4961-822a-ce6dbd38eff7
      in: path
      name: CertificateId
      required: true
      schema:
        type: string
      x-speakeasy-match: id
    controlPlaneId:
      name: controlPlaneId
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 9524ec7d-36d9-465d-a8c5-83a3c9390458
      description: The UUID of your control plane. This variable is available in the Konnect manager.
      x-speakeasy-param-force-new: true
    PaginationTagsFilter:
      allowEmptyValue: true
      description: A list of tags to filter the list of resources on. Multiple tags can be concatenated using ',' to mean AND or using '/' to mean OR.
      example: tag1,tag2
      in: query
      name: tags
      schema:
        type: string
  schemas:
    PaginationOffsetResponse:
      description: Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page
      type: string
    GatewayUnauthorizedError:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
      required:
      - message
      - status
    Certificate_2:
      description: 'A certificate object represents a public certificate, and can be optionally paired with the corresponding private key. These objects are used by Kong to handle SSL/TLS termination for encrypted requests, or for use as a trusted CA store when validating peer certificate of client/service. Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames. If intermediate certificates are required in addition to the main certificate, they should be concatenated together into one string according to the following order: main certificate on the top, followed by any intermediates.'
      type: object
      properties:
        cert:
          description: PEM-encoded public certificate chain of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).
          type: string
          x-referenceable: true
        cert_alt:
          description: PEM-encoded public certificate chain of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).
          type: string
          nullable: true
          x-referenceable: true
        created_at:
          description: Unix epoch when the resource was created.
          type: integer
          nullable: true
        id:
          description: A string representing a UUID (universally unique identifier).
          type: string
          nullable: true
        key:
          description: PEM-encoded private key of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).
          type: string
          x-encrypted: true
          x-referenceable: true
        key_alt:
          description: PEM-encoded private key of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).
          type: string
          nullable: true
          x-encrypted: true
          x-referenceable: true
        snis:
          type: array
          items:
            description: A string representing a wildcard host name, such as *.example.com.
            type: string
          nullable: true
        tags:
          description: An optional set of strings associated with the Certificate for grouping and filtering.
          type: array
          items:
            description: A string representing a tag.
            type: string
          nullable: true
        updated_at:
          description: Unix epoch when the resource was last updated.
          type: integer
          nullable: true
      example:
        cert: '-----BEGIN CERTIFICATE-----

          certificate-content

          -----END CERTIFICATE-----'
        id: b2f34145-0343-41a4-9602-4c69dec2f269
        key: '-----BEGIN PRIVATE KEY-----

          private-key-content

          -----END PRIVATE KEY-----'
      additionalProperties: false
      required:
      - cert
      - key
    Certificate:
      x-speakeasy-entity: Certificate
      description: 'A certificate object represents a public certificate, and can be optionally paired with the corresponding private key. These objects are used by Kong to handle SSL/TLS termination for encrypted requests, or for use as a trusted CA store when validating peer certificate of client/service. Certificates are optionally associated with SNI objects to tie a cert/key pair to one or more hostnames. If intermediate certificates are required in addition to the main certificate, they should be concatenated together into one string according to the following order: main certificate on the top, followed by any intermediates.'
      type: object
      properties:
        cert:
          description: PEM-encoded public certificate chain of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).
          type: string
          x-referenceable: true
        cert_alt:
          description: PEM-encoded public certificate chain of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).
          type: string
          nullable: true
          x-referenceable: true
        created_at:
          description: Unix epoch when the resource was created.
          type: integer
          nullable: true
        id:
          description: A string representing a UUID (universally unique identifier).
          type: string
          nullable: true
        key:
          description: PEM-encoded private key of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).
          type: string
          x-encrypted: true
          x-referenceable: true
        key_alt:
          description: PEM-encoded private key of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).
          type: string
          nullable: true
          x-encrypted: true
          x-referenceable: true
        snis:
          type: array
          items:
            description: A string representing a wildcard host name, such as *.example.com.
            type: string
          nullable: true
        tags:
          description: An optional set of strings associated with the Certificate for grouping and filtering.
          type: array
          items:
            description: A string representing a tag.
            type: string
          nullable: true
        updated_at:
          description: Unix epoch when the resource was last updated.
          type: integer
          nullable: true
      example:
        cert: '-----BEGIN CERTIFICATE-----

          certificate-content

          -----END CERTIFICATE-----'
        id: b2f34145-0343-41a4-9602-4c69dec2f269
        key: '-----BEGIN PRIVATE KEY-----

          private-key-content

          -----END PRIVATE KEY-----'
      additionalProperties: false
      required:
      - cert
      - key
    PaginationNextResponse:
      description: URI to the next page (may be null)
      type: string
  securitySchemes:
    adminToken:
      in: header
      name: Kong-Admin-Token
      type: apiKey
externalDocs:
  description: Documentation for Kong Gateway and its APIs
  url: https://developer.konghq.com