Device42 Certificates API

openapi: 3.2.0
info:
  title: Device42 Certificates API
  version: '2.0'
  description: 'API Overview


    RESTful APIs are supported in Device42 as one of the primary methods of entering, editing and retrieving data.'
  contact:
    name: Device42
    email: support@device42.com
servers:
- url: https://<host>
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Certificates
paths:
  /api/1.0/certificates/:
    get:
      operationId: get_certificates
      summary: Get
      description: This API is used to return the certificates you have added or discovered in Device42
      tags:
      - Certificates
      parameters:
      - name: certificate_id
        in: query
        description: ID of the certificate
        schema:
          type: string
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  total_count:
                    example: '1'
                  certificate_details:
                    type: array
                    items:
                      $ref: '#/components/schemas/Get_certificates'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: postUpdate_certificates
      summary: Create/update
      description: 'This API is used to update or add new certificates in bulk. Note: If you enter the DNS for the certificate, that is the only required field. Otherwise valid_from and valid_to are required'
      tags:
      - Certificates
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                id:
                  description: ID is only required if updating an existing certificate
                  type: string
                dns:
                  description: dns address of the site certificate is issued for.
                  type: string
                issued_to:
                  description: Entity certificate is issued to.
                  type: string
                issued_by:
                  description: The entity issuing the certificate
                  type: string
                valid_from:
                  description: The start date of the certificate. Required if creating a new certificate. YYYY-MM-DD format
                  type: string
                valid_to:
                  description: The expiration date of the certificate. Required if creating a new certificate. YYYY-MM-DD format
                  type: string
                subject:
                  description: The person, or entity identified.
                  type: string
                version:
                  description: The version of the encoded certificate
                  type: string
                serial_number:
                  description: Used to uniquely identify the certificate
                  type: string
                signature_algorithm:
                  description: The algorithm used to create the signature.
                  type: string
                signature_hash:
                  description: The actual signature to verify that it came from the issuer
                  type: string
                san:
                  description: Subject Alternative Name
                  type: string
                digital_signature_usage:
                  description: True when the subject public key is used for verifying digital signatures
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                content_commitment_usage:
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                key_encipherment_usage:
                  description: True when the subject public key is used for enciphering private or secret keys
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                data_encipherment_usage:
                  description: True when the subject public key is used for directly enciphering raw user data without the use of an intermediate symmetric cipher.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                key_agreement_usage:
                  description: True when the subject public key is used for key agreement.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                key_cert_sign_usage:
                  description: True when the subject public key is used for verifying signatures on public key certificates.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                crl_sign_usage:
                  description: True when the subject public key is used for verifying signatures on certificate revocation lists.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                encipher_only_usage:
                  description: When the encipherOnly bit is asserted and the keyAgreement bit is also set, the subject public key may be used only for enciphering data while performing key agreement.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                decipher_only_usage:
                  description: When the decipherOnly bit is asserted and the keyAgreement bit is also set, the subject public key may be used only for deciphering data while performing key agreement.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                extended_key_usage:
                  description: Indicates the purpose of the public key contained in the certificate. It contains a list of OIDs, each of which indicates an allowed use.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                vendor:
                  description: The name of the vendor that provided this certificate
                  type: string
                end_point_type:
                  type: string
                end_point_id:
                  type: string
                groups:
                  description: Use only if Multitenancy is on. List of groups separated by commas. Each group has name followed by colon followed by yes or no for change_permission, eg. CorpUS:yes, CorpNY:no.
                  type: string
                tags:
                  description: Comma separated list of tags
                  type: string
                tags_remove:
                  description: Comma separated list of tags to remove
                  type: string
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  msg:
                    example:
                    - certificate added/updated
                    - test.device42.com
                    - test.device42.com
                    - true
                    - true
                  code:
                    example: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/1.0/certificates/{ID}/:
    delete:
      operationId: deleteCertificates
      summary: Delete
      description: This API is used to delete the certificate with the certificate id supplied as the required argument
      tags:
      - Certificates
      parameters:
      - name: ID
        in: path
        description: certificate id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: 'true'
                  id:
                    example: '114'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/1.0/custom_fields/certificate/:
    put:
      operationId: put_CustomFields
      summary: Custom fields
      tags:
      - Certificates
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  description: Name of the certificate
                  type: string
                id:
                  description: ID of certificate
                  type: string
                key:
                  description: Can be new or existing. This is the custom field name.
                  type: string
                type:
                  description: this is the custom field type. If left blank, default is text. Date should be formatted as YYYY-MM-DD
                  type: string
                  enum:
                  - text
                  - number
                  - date
                  - related_field
                  - boolean
                  - url
                  - picklist
                  - json
                  - markup
                mandatory:
                  description: Is custom field mandatory? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                filterable:
                  description: Is custom field filterable? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                log_for_api:
                  description: Log custom field? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                related_field_name:
                  description: Required if type = related_field. The existing field to relate this custom field to. Below are details for some of the fields that have been renamed or require further clarification. appcomp (for application components), businessapp (for Business Service), circuit (for Telco Circuit), cloudinfrastructure (for Cloud Account),  hardware (for device hardware model), netport (for Switch Port), organisation (for Vendor), pdu (for Power Unit), pdu_model (for Power Unit Model), purchase (for Purchase Order), software (for Software Component), vlan (for Subnet)
                  type: string
                  enum:
                  - appcomp
                  - building
                  - businessapp
                  - certificate
                  - circuit
                  - cloudinfrastructure
                  - costcenter
                  - customer
                  - device
                  - dns_zone
                  - endusers
                  - hardware
                  - ip_address
                  - netport
                  - organisation
                  - os
                  - pdu
                  - pdu_model
                  - powercircuit
                  - purchase
                  - rack
                  - room
                  - servicecategory
                  - software_category
                  - software
                  - vlan
                add_to_picklist:
                  description: Comma separated values to add to picklist. If type is picklist and custom field is new, this is a required field. Duplicates will be ignored.
                  type: string
                remove_from_picklist:
                  description: Comma separated values to be removed from picklist. Duplicates will be ignored. Values that are in use will Not be deleted, unless <b>delete_in_use</b> parameter is provided and set to <b>yes</b>
                  type: string
                delete_in_use:
                  description: pass in <b>yes</b> if you want to delete Picklist value that is in use. Used in conjunction with <b>remove_from_picklist</b>.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                custom_field:
                  description: Custom Value
                  type: string
                related_field_value_by_id:
                  description: Select yes if you want to set the related field value by ID.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                value:
                  description: This will set the value of the custom field for the specific object.
                  type: string
                clear_value:
                  description: yes to clear existing value for that field
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                notes:
                  description: Any additional notes
                  type: string
                clear_notes:
                  description: Yes to clear any existing notes
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                bulk_fields:
                  description: comma separated key value pairs, with key and value separated by colon. e.g.key1:value1, key2:value2
                  type: string
                multi_select:
                  description: Applies only to Picklist fields. Is custom field multi select? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
              required:
              - id
              - key
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  msg:
                    example:
                    - custom key pair values added or updated
                    - 4
                    - Skynet
                  code:
                    example: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    Forbidden:
      description: Forbidden (The resource requested is hidden)
      content:
        application/json:
          example:
            errors:
            - code: 403
              reason: Forbidden
              title: Forbidden
              detail: The resource requested is hidden
    BadRequest:
      description: Bad Request (A validation exception has occurred.)
      content:
        application/json:
          example:
            errors:
            - code: 400
              reason: BAD_REQUEST
              title: The error response code title.
              detail: Details of the error response.
    Unauthorized:
      description: Unauthorized (Invalid credentials.)
      content:
        application/json:
          example:
            errors:
            - code: 401
              reason: Unauthorized
              title: Unauthorized
              detail: Invalid credentials.
    InternalServerError:
      description: Internal Server Error (A required parameter is missing or there is an issue with the server. Check the returned 'msg' field from the call.)
      content:
        application/json:
          example:
            errors:
            - code: 500
              reason: Internal Server Error
              title: Internal Server Error
              detail: A required parameter is missing or there is an issue with the server. Check the returned 'msg' field from the call.
    NotFound:
      description: Not Found (The specified resource could not be found)
      content:
        application/json:
          example:
            errors:
            - code: 404
              reason: Not Found
              title: Not Found
              detail: The specified resource could not be found.
    ServiceUnavailable:
      description: Service Unavailable (Please check if your Device42 instance is working normally.)
      content:
        application/json:
          example:
            errors:
            - code: 503
              reason: Service Unavailable
              title: Service Unavailable
              detail: Please check if your Device42 instance is working normally.
  schemas:
    Get_certificates:
      type: object
      properties:
        content_commitment_usage:
          example: false
        crl_sign_usage:
          example: false
        custom_fields:
          example: []
        data_encipherment_usage:
          example: false
        days_to_expiry:
          example: 1077
        decipher_only_usage:
          example: false
        digital_signature_usage:
          example: true
        encipher_only_usage:
          example: false
        extended_key_usage:
          example: 'SERVERAUTH(1.3.6.1.5.5.7.3.1)

            CLIENTAUTH(1.3.6.1.5.5.7.3.2)

            '
        id:
          example: '3'
        san:
          example: ''
        issued_by:
          example: ''
        issued_to:
          example: registration.device42.com
        key_agreement_usage:
          example: false
        key_cert_sign_usage:
          example: false
        key_encipherment_usage:
          example: true
        parent_cert:
          example: ''
        serial_number:
          example: 77eb9b55e9228635f2157fd374b8da8
        signature_algorithm:
          example: sha256WithRSAEncryption
        signature_hash:
          example: '708489795'
        subject:
          example: /OU=Domain Control Validated/OU=PositiveSSL/CN=registration.device42.com
        valid_from:
          example: '2014-08-10'
        valid_to:
          example: '2019-08-09'
        vendor:
          example: ''
        version:
          example: 2
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using a Device42 user's username and password.
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from POST /tauth/1.0/token/ using an API Client's key/secret as Basic auth credentials.