Mainflux.mainflux/authn/openapi.yml

openapi: 3.0.1
info:
  title: Mainflux authentication service
  description: HTTP API for managing platform API keys.
  version: "1.0.0"

paths:
  /keys:
    post:
      summary: Issue API key
      description: |
        Generates a new API key. Thew new API key will
        be uniquely identified by its ID.
      tags:
        - authn
      requestBody:
        $ref: "#/components/requestBodies/KeyRequest"
      responses:
        201:
          description: Issued new key.
        400:
          description: Failed due to malformed JSON.
        409:
          description: Failed due to using already existing ID.
        415:
          description: Missing or invalid content type.
        500:
          $ref: "#/components/responses/ServiceError"
  /keys/{id}:
    get:
      summary: Gets API key details.
      description: |
        Gets API key details for the given key.
      tags:
        - authn
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ID"
      responses:
        200:
          $ref: "#/components/responses/KeyRes"
        400:
          description: Failed due to malformed query parameters.
        403:
          description: Missing or invalid access token provided.
        500:
          $ref: "#/components/responses/ServiceError"
    delete:
      summary: Revoke API key
      description: |
        Revoke API key identified by the given ID.
      tags:
        - authn
      parameters:
        - $ref: "#/components/parameters/Authorization"
        - $ref: "#/components/parameters/ID"
      responses:
        204:
          description: Key revoked.
        403:
          description: Missing or invalid access token provided.
        500:
          $ref: "#/components/responses/ServiceError"

components:
  schemas:
    Key:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "c5747f2f-2a7c-4fe1-b41a-51a5ae290945"
          description: API key unique identifier
        type:
          type: integer
          example: 0
          description: API key type. Keys of different type are processed differently
        issuer:
          type: string
          format: string
          example: "test@example.com"
          description: User's email or service identifier of API key issuer
        secret:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiZXhhbXBsZSIsImlhdCI6MTUxNjIzOTAyMn0.9UYAFWmPIn4ojss36LpIGSqABZHfADQmVuKQ4PJBMdI
          description: API Key value.
        issued_at:
          type: string
          format: date-time
          example: "2019-11-26 13:31:52"
          description: Time when the key is generated
        expires_at:
          type: string
          format: date-time
          example: "2019-11-26 13:31:52"
          description: Time when the Key expires

  parameters:
    Authorization:
      name: Authorization
      description: Login key secret (User's access token).
      in: header
      schema:
        type: string
      required: true
    ID:
      name: id
      description: API Key id.
      in: path
      schema:
        type: string
      required: true

  requestBodies:
    KeyRequest:
      description: JSON-formatted document describing key request.
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: integer
                example: 0
                description: API key type. Keys of different type are processed differently
              issuer:
                type: string
                format: e-mail
                example: "test@example.com"
                description: User's email or service identifier of API key issuer
              duration:
                type: number
                format: integer
                example: 23456
                description: Number of seconds issued token is valid for.

  responses:
    ServiceError:
      description: Unexpected server-side error occurred.
    KeyRes:
      description: Data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Key"