supermq/api/openapi/certs.yml

# Copyright (c) Abstract Machines
# SPDX-License-Identifier: Apache-2.0

openapi: 3.0.1
info:
  title: Magistrala Certs service
  description: |
    HTTP API for Certs service
    Some useful links:
    - [The Magistrala repository](https://github.com/absmach/magistrala)
  contact:
    email: info@mainflux.com
  license:
    name: Apache 2.0
    url: https://github.com/absmach/magistrala/blob/master/LICENSE
  version: 0.14.0

servers:
  - url: http://localhost:9019
  - url: https://localhost:9019

tags:
  - name: certs
    description: Everything about your Certs
    externalDocs:
      description: Find out more about certs
      url: http://docs.mainflux.io/

paths:
  /certs:
    post:
      summary: Creates a certificate for thing
      description: Creates a certificate for thing
      tags:
        - certs
      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/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/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/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:
    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 Magistrala 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
            properties:
               thing_id:
                 type: string
                 format: uuid
               ttl:
                 type: string
                 example: "10h"

  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"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        * Users access: "Authorization: Bearer <user_token>"

security:
  - bearerAuth: []