Mainflux.mainflux/api/openapi/certs.yml

openapi: 3.0.1
info:
  title: Mainflux Certs service
  description: HTTP API for Certs service
  version: "1.0.0"

paths:
  /certs:
    post:
      summary: Creates a certificate for thing
      description: Creates a certificate for thing
      tags:
        - certs
      parameters:
      - $ref: "#/components/parameters/Authorization"
      requestBody:
        $ref: "#/components/requestBodies/CertReq"
      responses:
        '201':
          description: Created
        '400':
          description: Failed due to malformed JSON.
        "401":
          description: Missing or invalid access token provided.
        '500':
          description: Unexpected server-side error ocurred.
  /certs/{certID}:
    get:
      summary: Retrieves a certificate
      description: |
        Retrieves a certificate for a given cert ID.
      tags:
        - certs
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/CertID"
      responses:
        '200':
          $ref: "#/components/responses/CertRes"
        '400':
          description: Failed due to malformed query parameters.
        "401":
          description: Missing or invalid access token provided.
        '404':
          description: |
            Failed to retrieve corresponding certificate.
        '500':
          $ref: "#/components/responses/ServiceError"
    delete:
      summary: Revokes a certificate
      description: |
        Revokes a certificate for a given cert ID.
      tags:
        - certs
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/CertID"
      responses:
        '200':
          $ref: "#/components/responses/RevokeRes"
        "401":
          description: Missing or invalid access token provided.
        '404':
          description: |
            Failed to revoke corresponding certificate.
        '500':
          $ref: "#/components/responses/ServiceError"
  /serials/{thingID}:
    get:
      summary: Retrieves certificates' serial IDs
      description: |
        Retrieves a list of certificates' serial IDs for a given thing ID.
      tags:
        - certs
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ThingID"
      responses:
        '200':
          $ref: "#/components/responses/SerialsPageRes"
        '400':
          description: Failed due to malformed query parameters.
        "401":
          description: Missing or invalid access token provided.
        '404':
          description: |
            Failed to retrieve corresponding certificates.
        '500':
          $ref: "#/components/responses/ServiceError"
  /health:
    get:
      summary: Retrieves service health check info.
      tags:
        - health
      responses:
        '200':
          $ref: "#/components/responses/HealthRes"
        '500':
          $ref: "#/components/responses/ServiceError"

components:
  parameters:
    Authorization:
      name: Authorization
      description: User's access token. Used instead of credentials in env or config.toml.
      in: header
      schema:
        type: string
      required: false
    ThingID:
      name: thingID
      description: Thing ID
      in: path
      schema:
        type: string
        format: uuid
      required: true
    CertID:
      name: certID
      description: Serial of certificate
      in: path
      schema:
        type: string
        format: uuid
      required: true

  schemas:
    Cert:
      type: object
      properties:
        thing_id:
          type: string
          format: uuid
          description: Corresponding Mainflux Thing ID.
        client_cert:
          type: string
          description: Client Certificate.
        client_key:
          type: string
          description: Key for the client_cert.
        issuing_ca:
          type: string
          description: CA Certificate that is used to issue client certs, usually intermediate.
        serial:
          type: string
          description: Certificate serial
        expire:
          type: string
          description: Certificate expiry date
    Serial:
      type: object
      properties:
        serial:
          type: string
          description: Certificate serial
    CertsPage:
      type: object
      properties:
        certs:
          type: array
          minItems: 0
          uniqueItems: true
          items:
            $ref: "#/components/schemas/Cert"
        total:
          type: integer
          description: Total number of items.
        offset:
          type: integer
          description: Number of items to skip during retrieval.
        limit:
          type: integer
          description: Maximum number of items to return in one page.
    SerialsPage:
      type: object
      properties:
        serials:
          type: array
          description: Certificate serials IDs.
          minItems: 0
          uniqueItems: true
          items:
            type: string
        total:
          type: integer
          description: Total number of items.
        offset:
          type: integer
          description: Number of items to skip during retrieval.
        limit:
          type: integer
          description: Maximum number of items to return in one page.
    Revoke:
      type: object
      properties:
        revocation_time:
          type: string
          description: Certificate revocation time

  requestBodies:
    CertReq:
      description: |
          Issues a certificate that is required for mTLS. To create a certificate for a thing
          provide a thing id, data identifying particular thing will be embedded into the Certificate.
          x509 and ECC certificates are supported when using when Vault is used as PKI.
      content:
        application/json:
          schema:
            type: object
            required:
              - thing_id
              - ttl
              - key_bits
              - key_type
            properties:
               thing_id:
                 type: string
                 format: uuid
               ttl:
                 type: string
               key_type:
                 type: string
               key_bits:
                 type: integer

  responses:
    ServiceError:
      description: Unexpected server-side error occurred.
    CertRes:
      description: Certificate data.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Cert"
    CertsPageRes:
      description: Certificates page.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CertsPage"
    SerialsPageRes:
      description: Serials page.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SerialsPage"
    RevokeRes:
      description: Certificate revoked.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Revoke"
    HealthRes:
      description: Service Health Check.
      content:
        application/json:
          schema:
            $ref: "./schemas/HealthInfo.yml"