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/ID"
      security:
      - Authorization: []
      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/ID"
      security:
      - Authorization: []
      responses:
        '204':
          description: Key revoked.
        '403':
          description: Missing or invalid access token provided.
        '500':
          $ref: "#/components/responses/ServiceError"

components:
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Key:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "c5747f2f-2a7c-4fe1-b41a-51a5ae290945"
          description: API key unique identifier
        issuer_id:
          type: string
          format: UUID
          example: "9118de62-c680-46b7-ad0a-21748a52833a"
          description: In ID of the entity that issued the token.
        type:
          type: integer
          example: 0
          description: API key type. Keys of different type are processed differently.
        subject:
          type: string
          format: string
          example: "test@example.com"
          description: User's email or service identifier of API key subject.
        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. If this field is missing,
            that means that Key is valid indefinitely.

  parameters:
    ID:
      name: id
      description: API Key id.
      in: path
      schema:
        type: string
        format: UUID
      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.
              token:
                type: string
                format: JWT
                example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiZXhhbXBsZSIsImlhdCI6MTUxNjIzOTAyMn0.9UYAFWmPIn4ojss36LpIGSqABZHfADQmVuKQ4PJBMdI"
                description: JWT for the entity that's sending Key request.
              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"