Tyk Certificates API

openapi: 3.2.0
info:
  contact:
    email: support@tyk.io
    name: Tyk Technologies
    url: https://tyk.io/contact
  description: '

    ## <a name="introduction"></a> Introduction


    The Tyk Dashboard API offers granular, programmatic access to a centralised database of resources that your Tyk nodes can pull from. This API has a dynamic user administrative structure which means the secret key that is used to communicate with your Tyk nodes can be kept secret and access to the wider management functions can be handled on a user-by-user and organisation-by-organisation basis.


    A common question around using a database-backed configuration is how to programmatically add API definitions to your Tyk nodes, the Dashboard API allows much more fine-grained, secure and multi-user access to your Tyk cluster, and should be used to manage a database-backed Tyk node.


    The Tyk Dashboard API works seamlessly with the Tyk Dashboard (and the two come bundled together).


    ## <a name="security-hierarchy"></a> Security Hierarchy


    The Dashboard API provides a more structured security layer to managing Tyk nodes.


    ### Organisations, APIs and Users


    With the Dashboard API and a database-backed Tyk setup, (and to an extent with file-based API setups - if diligence is used in naming and creating definitions), the following security model is applied to the management of Upstream APIs:


    * **Organisations**: All APIs are *owned* by an organisation, this is designated by the ''OrgID'' parameter in the API Definition.

    * **Users**: All users created in the Dashboard belong to an organisation (unless an exception is made for super-administrative access).

    * **APIs**: All APIs belong to an Organisation and only Users that belong to that organisation can see the analytics for those APIs and manage their configurations.

    * **API Keys**: API Keys are designated by organisation, this means an API key that has full access rights will not be allowed to access the APIs of another organisation on the same system, but can have full access to all APIs within the organisation.

    * **Access Rights**: Access rights are stored with the key, this enables a key to give access to multiple APIs, this is defined by the session object in the core Tyk API.


    In order to use the Dashboard API, you''ll need to get the ''Tyk Dashboard API Access Credentials'' secret from your user profile on the Dashboard UI.


    The secret you set should then be sent along as a header with each Dashboard API Request in order for it to be successful:



    authorization: <your-secret>

    '
  license:
    name: Mozilla Public License Version 2.0
    url: https://github.com/TykTechnologies/tyk/blob/master/LICENSE.md
  title: Tyk Dashboard Certificates API
  version: 5.7.1
servers:
- url: https://{tenant}
  variables:
    tenant:
      default: localhost:8080
      description: Your dashboard host
security:
- bearerAuth: []
tags:
- description: Use the endpoints under this tag to manage your certificates. You can add, delete and list certificates using these endpoints.
  name: Certificates
paths:
  /api/certs:
    get:
      description: Return list of certificates. If you send the mode query parameter with the value `detailed` the certificates returned will have more information (Will contains all certs basic details). To retrieve a list with complete certificate details use [this endpoint](#operation/listDetailedCertificates). If the mode query parameter is omitted or is empty this endpoint will only return the certificates IDs. The list of certificates returned is paginated.
      operationId: listCertificates
      parameters:
      - description: Use p query parameter to say which page you want returned. Send number less than 0 to return all items.
        example: 1
        in: query
        name: p
        required: false
        schema:
          type: integer
      - description: Set to detailed to get certificates that are more with more details (Will contains certs basic details). To retrieve a list of certificates with all the certificate details use [this endpoint](#operation/listDetailedCertificates).
        example: detailed
        in: query
        name: mode
        required: false
        schema:
          enum:
          - detailed
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                detailed_mode:
                  summary: Returned when you send mode=detailed in query parameter.
                  value:
                    cert_basics:
                    - dns_names:
                      - .*itachi.io
                      has_private: false
                      id: 5e9d9544a1dcd60001d0ed208edce514c2d0a866063550c64d6c90be99d01561ac5aa7e82b8610b7e273d37d
                      is_ca: false
                      issuer_cn: tyk-gateway-2.localhost
                      not_after: '2025-05-19T05:23:10Z'
                      not_before: '2024-05-19T05:23:10Z'
                      subject_cn: tyk-gateway-2.localhost
                    - dns_names:
                      - .*tyk.io
                      has_private: false
                      id: 5e9d9544a1dcd60001d0ed207c440d66ebb0a4629d21329808dce9091acf5f2fde328067a6e60e5347271d90
                      is_ca: false
                      issuer_cn: tyk.io
                      not_after: '2034-03-26T08:46:37Z'
                      not_before: '2024-03-25T08:46:37Z'
                      subject_cn: tyk.io
                    pages: 1
                empty_mode:
                  summary: Returned if `mode` in query parameter is empty.
                  value:
                    certs:
                    - 5e9d9544a1dcd60001d0ed208edce514c2d0a866063550c64d6c90be99d01561ac5aa7e82b8610b7e273d37d
                    - 5e9d9544a1dcd60001d0ed207c440d66ebb0a4629d21329808dce9091acf5f2fde328067a6e60e5347271d90
                    pages: 1
              schema:
                oneOf:
                - $ref: '#/components/schemas/CertificateBasics'
                - $ref: '#/components/schemas/CertificateList'
          description: OK
        '400':
          content:
            application/json:
              example:
                Message: Could not retrieve certs.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unable to retrieve certificates.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/certs'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              example:
                Message: Failed to marshal data for certificates basics list.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: List Certificates.
      tags:
      - Certificates
    post:
      description: Upload new SSL certificate in PEM format (you should upload as a file). If the certificate should have a private key, convert both the public certificate and the associated private key to PEM format and concatenate them to a single file. You can only upload one certificate at a time.
      operationId: createCertificates
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FormDataFile'
        description: File containing the certs.
      responses:
        '200':
          content:
            application/json:
              example:
                id: 5e9d9544a1dcd60001d0ed208edce514c2d0a866063550c64d6c90be99d01561ac5aa7e82b8610b7e273d37d
                message: Certificate added.
                status: ok
              schema:
                $ref: '#/components/schemas/APICertificateStatusMessage'
          description: Certificates created.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/certs'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              example:
                Message: Could not create certificate.Certificate with 5e9d9... ID already exists.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: unable to create certs
        '500':
          content:
            application/json:
              example:
                Message: Failed to read response body, body empty.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Sending data without the certs file.
      summary: Create a certificate in Tyk org cert store.
      tags:
      - Certificates
  /api/certs/{certId}:
    delete:
      description: Delete certificate by their ID.
      operationId: deleteCertificates
      parameters:
      - description: ID of the certificate you want to delete.
        example: 5e9d9544a1dcd60001d0ed208edce514c2d0a866063550c64d6c90be99d01561ac5aa7e82b8610b7e273d37d
        in: path
        name: certId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                message: message
                status: status
              schema:
                $ref: '#/components/schemas/ApiStatusMessage'
          description: Certs deleted.
        '400':
          content:
            application/json:
              example:
                Message: Attempted access to non-owned certificate.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Trying to delete certs you don't own.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/certs/{certId}'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              example:
                Message: Could not delete certificate.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Failed to delete certs.
      summary: Delete Certificate.
      tags:
      - Certificates
    get:
      description: Get a single certificate details with the certificate's ID.
      operationId: getCertificate
      parameters:
      - description: ID of the certificate you want to fetch.
        example: 5e9d9544a1dcd60001d0ed208edce514c2d0a866063550c64d6c90be99d01561ac5aa7e82b8610b7e273d37d
        in: path
        name: certId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                dns_names:
                - .*tyk.io
                fingerprint: 7c440d66ebb0a4629d21329808dce9091acf5f2fde328067a6e60e5347271d90
                has_private: false
                id: 5e9d9544a1dcd60001d0ed207c440d66ebb0a4629d21329808dce9091acf5f2fde328067a6e60e5347271d90
                is_ca: false
                issuer:
                  CommonName: tyk.io
                  Country:
                  - 'Peachtree '
                  ExtraNames:
                  - Type:
                    - 2
                    - 5
                    - 4
                    - 6
                    Value: 'Peachtree '
                  Locality:
                  - JN
                  Names:
                  - Type:
                    - 2
                    - 5
                    - 4
                    - 6
                    Value: Peachtree
                  - Type:
                    - 2
                    - 5
                    - 4
                    - 10
                    Value: tyk
                  - Type:
                    - 2
                    - 5
                    - 4
                    - 11
                    Value: tyk
                  - Type:
                    - 2
                    - 5
                    - 4
                    - 3
                    Value: tyk.io
                  - Type:
                    - 1
                    - 2
                    - 840
                    - 113549
                    - 1
                    - 9
                    - 1
                    Value: support@tyk.io
                  Organization:
                  - tyk
                  OrganizationalUnit:
                  - tyk
                  PostalCode:
                  - '00010'
                  Province:
                  - San Jore
                  SerialNumber: ''
                  StreetAddress:
                  - River side drive
                not_after: '2034-03-26T08:46:37Z'
                not_before: '2024-03-25T08:46:37Z'
                subject:
                  CommonName: tyk.io
                  Country:
                  - 'Peachtree '
                  ExtraNames:
                  - Type:
                    - 2
                    - 5
                    - 4
                    - 6
                    Value: 'Peachtree '
                  Locality:
                  - JN
                  Names:
                  - Type:
                    - 2
                    - 5
                    - 4
                    - 6
                    Value: 'Peachtree '
                  - Type:
                    - 2
                    - 5
                    - 4
                    - 10
                    Value: tyk
                  - Type:
                    - 2
                    - 5
                    - 4
                    - 11
                    Value: tyk
                  - Type:
                    - 2
                    - 5
                    - 4
                    - 3
                    Value: tyk.io
                  - Type:
                    - 1
                    - 2
                    - 840
                    - 113549
                    - 1
                    - 9
                    - 1
                    Value: support@tyk.io
                  Organization:
                  - tyk
                  OrganizationalUnit:
                  - tyk
                  PostalCode:
                  - '00010'
                  Province:
                  - San Jore
                  SerialNumber: ''
                  StreetAddress:
                  - River side drive
              schema:
                $ref: '#/components/schemas/CertsCertificateMeta'
          description: Certificates fetched.
        '400':
          content:
            application/json:
              example:
                Message: Attempted access to non-owned certificate.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Trying to fetch certs you don't own.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/certs/{certId}'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              example:
                Message: Could not retrieve certificate details. Certificate with given SHA256 fingerprint not found.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Failed to fetch certs.
      summary: Get single certificate with ID.
      tags:
      - Certificates
  /api/certs/dependencies/{certId}:
    delete:
      description: This endpoint will remove the certificates from any APIs that contains it as an upstream certificates or as a client certificate. It will also remove any key that uses this certificate.
      operationId: deleteCertificateDependencies
      parameters:
      - description: ID of the certificate you want to delete dependencies for.
        example: 5e9d9544a1dcd60001d0ed208edce514c2d0a866063550c64d6c90be99d01561ac5aa7e82b8610b7e273d37d
        in: path
        name: certId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                Message: Certificate dependencies deletion successfully attempted.
                Meta: null
                Status: OK
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Dependencies deleted.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/certs/dependencies/{certId}'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
      summary: Delete Certificate dependencies.
      tags:
      - Certificates
    get:
      description: This will return the API IDs and API names of all APIs that uses this certificates as either upstream certificates or as client certificates.
      operationId: getCertificateDependencies
      parameters:
      - description: ID of the certificate you want to fetch dependencies for.
        example: 5e9d9544a1dcd60001d0ed208edce514c2d0a866063550c64d6c90be99d01561ac5aa7e82b8610b7e273d37d
        in: path
        name: certId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                certID: 5e9d9544a1dcd60001d0ed20a6ab77653d5da938f452bb8cc9b55b0630a6743dabd8dc92bfb025abb09ce035
                client_cert_api_names:
                - Ngrok Dashboard API
                client_cert_apis:
                - edc9b2bd3e7b4cc55c4ff0a7e1529b45
                key_cert: 5e9d9544a1dcd60001d0ed205e9d9544a1dcd60001d0ed20a6ab77653d5da938f452bb8cc9b55b0630a6743dabd8dc92bfb025abb09ce035
                upstream_cert_api_names:
                - External HTTPbin
                upstream_cert_apis:
                - 627efb71ebae49df7a853b9769b65fce
              schema:
                $ref: '#/components/schemas/CertificateDependencies'
          description: Dependencies fetched.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/certs/dependencies/{certId}'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
      summary: Get Certificate Dependencies.
      tags:
      - Certificates
  /api/certs/details:
    get:
      description: Return a list that contains certificates and their full details.
      operationId: listDetailedCertificates
      parameters:
      - description: Use p query parameter to say which page you want returned. Send number less than 0 to return all items.
        example: 1
        in: query
        name: p
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                certificates:
                - dns_names:
                  - .*tyk.io
                  fingerprint: 7c440d66ebb0a4629d21329808dce9091acf5f2fde328067a6e60e5347271d90
                  has_private: false
                  id: 5e9d9544a1dcd60001d0ed207c440d66ebb0a4629d21329808dce9091acf5f2fde328067a6e60e5347271d90
                  is_ca: false
                  issuer:
                    CommonName: tyk.io
                    Country:
                    - 'Peachtree '
                    ExtraNames:
                    - Type:
                      - 2
                      - 5
                      - 4
                      - 6
                      Value: 'Peachtree '
                    Locality:
                    - JN
                    Names:
                    - Type:
                      - 2
                      - 5
                      - 4
                      - 6
                      Value: Peachtree
                    - Type:
                      - 2
                      - 5
                      - 4
                      - 10
                      Value: tyk
                    - Type:
                      - 2
                      - 5
                      - 4
                      - 11
                      Value: tyk
                    - Type:
                      - 2
                      - 5
                      - 4
                      - 3
                      Value: tyk.io
                    - Type:
                      - 1
                      - 2
                      - 840
                      - 113549
                      - 1
                      - 9
                      - 1
                      Value: support@tyk.io
                    Organization:
                    - tyk
                    OrganizationalUnit:
                    - tyk
                    PostalCode:
                    - '00010'
                    Province:
                    - San Jore
                    SerialNumber: ''
                    StreetAddress:
                    - River side drive
                  not_after: '2034-03-26T08:46:37Z'
                  not_before: '2024-03-25T08:46:37Z'
                  subject:
                    CommonName: tyk.io
                    Country:
                    - 'Peachtree '
                    ExtraNames:
                    - Type:
                      - 2
                      - 5
                      - 4
                      - 6
                      Value: 'Peachtree '
                    Locality:
                    - JN
                    Names:
                    - Type:
                      - 2
                      - 5
                      - 4
                      - 6
                      Value: 'Peachtree '
                    - Type:
                      - 2
                      - 5
                      - 4
                      - 10
                      Value: tyk
                    - Type:
                      - 2
                      - 5
                      - 4
                      - 11
                      Value: tyk
                    - Type:
                      - 2
                      - 5
                      - 4
                      - 3
                      Value: tyk.io
                    - Type:
                      - 1
                      - 2
                      - 840
                      - 113549
                      - 1
                      - 9
                      - 1
                      Value: support@tyk.io
                    Organization:
                    - tyk
                    OrganizationalUnit:
                    - tyk
                    PostalCode:
                    - '00010'
                    Province:
                    - San Jore
                    SerialNumber: ''
                    StreetAddress:
                    - River side drive
                pages: 1
              schema:
                $ref: '#/components/schemas/CertificateDetailedList'
          description: Fetched certificates.
        '400':
          content:
            application/json:
              example:
                Message: Could not retrieve certs details.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Could not connect to gateway.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/certs/details'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              example:
                Message: Failed to marshal data for certificate list.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: List all certificates details.
      tags:
      - Certificates
components:
  schemas:
    APICertificateStatusMessage:
      properties:
        id:
          example: 5e9d9544a1dcd60001d0ed207c440d66ebb0a4629d21329808dce9091acf5f2fde328067a6e60e5347271d90
          type: string
        message:
          example: Certificate added
          type: string
        status:
          example: ok
          type: string
      type: object
      x-go-package: github.com/TykTechnologies/tyk/gateway
    CertsCertificateBasics:
      properties:
        dns_names:
          items:
            type: string
          type:
          - array
          - 'null'
        has_private:
          type: boolean
        id:
          type: string
        is_ca:
          type: boolean
        issuer_cn:
          type: string
        not_after:
          format: date-time
          type: string
        not_before:
          format: date-time
          type: string
        subject_cn:
          type: string
      type: object
      x-go-package: github.com/TykTechnologies/tyk/certs
    MultipartFile:
      format: binary
      type:
      - string
      - 'null'
    FormDataFile:
      properties:
        file:
          $ref: '#/components/schemas/MultipartFile'
      required:
      - file
      type: object
    CertificateDetailedList:
      properties:
        certificates:
          items:
            $ref: '#/components/schemas/CertsCertificateMeta'
          type:
          - array
          - 'null'
        pages:
          type: integer
      type: object
    CertificateList:
      properties:
        certs:
          items:
            type: string
          type:
          - array
          - 'null'
        pages:
          type: integer
      type: object
    PkixName:
      type: object
    CertificateDependencies:
      properties:
        certID:
          example: 5e9d9544a1dcd60001d0ed20a6ab77653d5da938f452bb8cc9b55b0630a6743dabd8dc92bfb025abb09ce035
          type: string
        client_cert_api_names:
          example:
          - Ngrok Dashboard API
          items:
            type: string
          type:
          - array
          - 'null'
        client_cert_apis:
          example:
          - edc9b2bd3e7b4cc55c4ff0a7e1529b45
          items:
            type: string
          type:
          - array
          - 'null'
        key_cert:
          example: 5e9d9544a1dcd60001d0ed205e9d9544a1dcd60001d0ed20a6ab77653d5da938f452bb8cc9b55b0630a6743dabd8dc92bfb025abb09ce035
          type: string
        upstream_cert_api_names:
          example:
          - External HTTPbin
          items:
            type: string
          type:
          - array
          - 'null'
        upstream_cert_apis:
          example:
          - 627efb71ebae49df7a853b9769b65fce
          items:
            type: string
          type:
          - array
          - 'null'
      type: object
    ApiResponse:
      properties:
        ID:
          type: string
        Message:
          type: string
        Meta: {}
        Status:
          type: string
      type: object
    ApiStatusMessage:
      properties:
        message:
          type: string
        status:
          type: string
      type: object
      x-go-package: github.com/TykTechnologies/tyk/gateway
    CertsCertificateMeta:
      properties:
        dns_names:
          items:
            type: string
          type: array
        fingerprint:
          type: string
        has_private:
          type: boolean
        id:
          type: string
        is_ca:
          type: boolean
        issuer:
          $ref: '#/components/schemas/PkixName'
        not_after:
          format: date-time
          type: string
        not_before:
          format: date-time
          type: string
        subject:
          $ref: '#/components/schemas/PkixName'
      type: object
      x-go-package: github.com/TykTechnologies/tyk/certs
    CertificateBasics:
      properties:
        cert_basics:
          items:
            $ref: '#/components/schemas/CertsCertificateBasics'
          type:
          - array
          - 'null'
        pages:
          type: integer
      type: object
  securitySchemes:
    bearerAuth:
      description: The Tyk Dashboard API Access Credentials
      scheme: bearer
      type: http