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:
        - auth
      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:
        - auth
      parameters:
        - $ref: "#/components/parameters/ApiKeyId"
      responses:
        '200':
          $ref: "#/components/responses/KeyRes"
        '400':
          description: Failed due to malformed query parameters.
        '401':
          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:
        - auth
      parameters:
        - $ref: "#/components/parameters/ApiKeyId"
      responses:
        '204':
          description: Key revoked.
        '401':
          description: Missing or invalid access token provided.
        '500':
          $ref: "#/components/responses/ServiceError"
  /groups:
    post:
      summary: Creates new group
      description: |
        Creates new group that can be used for grouping entities - things, users.
      tags:
        - auth
      parameters:
        - $ref: "#/components/requestBodies/GroupCreateReq"
      responses:
        '201':
          $ref: "#/components/responses/GroupCreateRes"
        '400':
          description: Failed due to malformed JSON.
        '409':
          description: Failed due to using an existing email address.
        '415':
          description: Missing or invalid content type.
        '500':
          $ref: "#/components/responses/ServiceError"
    get:
      summary: Gets all groups.
      description: |
        Gets all groups up to a max level of hierarchy that can be fetched in one
        request ( max level = 5). Result can be filtered by metadata. Groups will
        be returned as JSON array or JSON tree.
      tags:
        - auth
      parameters:
        - $ref: "#/components/parameters/Level"
        - $ref: "#/components/parameters/Metadata"
        - $ref: "#/components/parameters/Tree"
      responses:
        '200':
          $ref: "#/components/responses/GroupsPageRes"
        '400':
          description: Failed due to malformed query parameters.
        '401':
          description: Missing or invalid access token provided.
        '404':
          description: Group does not exist.
        '500':
          $ref: "#/components/responses/ServiceError"
  /groups/{groupId}:
    get:
      summary: Gets group info.
      description: |
        Gets info on a group specified by id.
      tags:
        - auth
      parameters:
        - $ref: "#/components/parameters/GroupId"
      responses:
        '200':
          $ref: "#/components/responses/GroupRes"
        '400':
          description: Failed due to malformed query parameters.
        '401':
          description: Missing or invalid access token provided.
        '404':
          description: Group does not exist.
        '500':
          $ref: "#/components/responses/ServiceError"
    put:
      summary: Updates group data.
      description: |
        Updates Name, Description or Metadata of a group.
      tags:
        - auth
      parameters:
        - $ref: "#/components/parameters/GroupId"
      requestBody:
        $ref: "#/components/requestBodies/GroupUpdateReq"
      responses:
        '200':
          description: Group updated.
        '400':
          description: Failed due to malformed query parameters.
        '401':
          description: Missing or invalid access token provided.
        '404':
          description: Group does not exist.
        '500':
          $ref: "#/components/responses/ServiceError"
    delete:
      summary: Deletes group.
      description: |
        Deletes group. If group is parent and descendant groups do not have any members
        child groups will be deleted. Group cannot be deleted if has members or if
        any descendant group has members.
      tags:
        - auth
      parameters:
        - $ref: "#/components/parameters/GroupId"
        - $ref: "#/components/parameters/Level"
        - $ref: "#/components/parameters/Metadata"
        - $ref: "#/components/parameters/Tree"
      responses:
        '204':
          description: Group removed.
        '400':
          description: Failed due to malformed query parameters.
        '401':
          description: Missing or invalid access token provided.
        '404':
          description: Group does not exist.
        '500':
          $ref: "#/components/responses/ServiceError"
  /groups/{groupId}/children:
    get:
      summary: Gets group children.
      description: |
        Gets the whole tree of descendants of group for given id including itself.
        For performance reason request is limited up to a given level of hierarchy
        (max. 5).
      tags:
        - auth
      parameters:
        - $ref: "#/components/parameters/GroupId"
        - $ref: "#/components/parameters/Level"
        - $ref: "#/components/parameters/Metadata"
        - $ref: "#/components/parameters/Tree"
      responses:
        '200':
          $ref: "#/components/responses/GroupsPageRes"
        '400':
          description: Failed due to malformed query parameters.
        '401':
          description: Missing or invalid access token provided.
        '404':
          description: Group does not exist.
        '500':
          $ref: "#/components/responses/ServiceError"
  /groups/{groupId}/parents:
    get:
      summary: Gets group info.
      description: |
        Gets a direct line of ancestors for a group specified by id.
        Result is up to a specified hierarchy level or up to a root group.
        Result can be a JSON array or a JSON tree.
      tags:
        - auth
      parameters:
        - $ref: "#/components/parameters/GroupId"
        - $ref: "#/components/parameters/Level"
        - $ref: "#/components/parameters/Metadata"
        - $ref: "#/components/parameters/Tree"
      responses:
        '200':
          $ref: "#/components/responses/GroupsPageRes"
        '400':
          description: Failed due to malformed query parameters.
        '401':
          description: Missing or invalid access token provided.
        '404':
          description: Group does not exist.
        '500':
          $ref: "#/components/responses/ServiceError"
  /groups/{groupId}/members:
    post:
      summary: Assigns members to a group.
      description: |
        Assigns thing or user id to a group.
      tags:
        - auth
      parameters:
        - $ref: "#/components/parameters/GroupId"
      requestBody:
        $ref: "#/components/requestBodies/MembersReq"
      responses:
        '201':
          $ref: "#/components/responses/GroupCreateRes"
        '400':
          description: Failed due to malformed JSON.
        '401':
          description: Missing or invalid access token provided.
        '409':
          description: Failed due to using an existing email address.
        '415':
          description: Missing or invalid content type.
        '500':
          $ref: "#/components/responses/ServiceError"
    get:
      summary: Gets members of a group.
      description: |
        Array of member ids that are in the group specified with groupID.
      parameters:
        - $ref: "#/components/parameters/GroupId"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Limit"
      responses:
        '200':
          $ref: "#/components/responses/MembersRes"
        '401':
          description: Missing or invalid access token provided.
        '500':
          $ref: "#/components/responses/ServiceError"
  /groups/{userGroupID}/share:
    post:
      summary: Adds access rights on thing groups to user group with userGroupID.
      description: |
        Takes user group id through parameter and adds access rights for user group on thing group received via request body.
      tags:
        - auth
      parameters:
        - $ref: "#/components/parameters/UserGroupID"
      requestBody:
        $ref: "#/components/requestBodies/ShareGroupAccessReq"
      responses:
        '200':
          description: User group shared with thing group.
        '400':
          description: Failed due to malformed JSON.
        '401':
          description: Missing or invalid access token provided.
        '415':
          description: Missing or invalid content type.
        '500':
          $ref: "#/components/responses/ServiceError"
  /members/{memberId}/groups:
    get:
      summary: Gets memberships for a member with member id.
      description: |
        Array of groups that member belongs to.
      parameters:
        - $ref: "#/components/parameters/MemberId"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Metadata"
      responses:
        '200':
          $ref: "#/components/responses/GroupRes"
        '401':
          description: Missing or invalid access token provided.
        '500':
          $ref: "#/components/responses/ServiceError"
  /policies:
    post:
      summary: Creates new policies.
      description: |
        Creates new policies. Only admin can use this endpoint. Therefore, you need an authentication token for the admin.
        Also, only policies defined on the system are allowed to add. For more details, please see the docs for Authorization.
      tags:
        - auth
      requestBody:
        $ref: "#/components/requestBodies/PoliciesReq"
      responses:
        '201':
          description: Policies created.
        '400':
          description: Failed due to malformed JSON.
        '401':
          description: Missing or invalid access token provided.
        '403':
          description: Unauthorized access token provided.
        '409':
          description: Failed due to using an existing email address.
        '415':
          description: Missing or invalid content type.
        '500':
          $ref: "#/components/responses/ServiceError"
    put:
      summary: Deletes policies.
      description: |
        Deletes policies. Only admin can use this endpoint. Therefore, you need an authentication token for the admin.
        Also, only policies defined on the system are allowed to delete. For more details, please see the docs for Authorization.
      tags:
        - auth
      requestBody:
        $ref: "#/components/requestBodies/PoliciesReq"
      responses:
        '204':
          description: Policies deleted.
        '400':
          description: Failed due to malformed JSON.
        '409':
          description: Failed due to using an existing email address.
        '415':
          description: Missing or invalid content type.
        '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:
  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.
    GroupReqSchema:
      type: object
      properties:
        name:
          type: string
          description: |
            Free-form group name. Group name is unique on the given hierarchy level.
        description:
          type: string
          description: Group description, free form text.
        parent_id:
          type: string
          format: ulid
          description: Id of parent group, it must be existing group.
        metadata:
          type: object
          description: Arbitrary, object-encoded group's data.
    GroupUpdateSchema:
      type: object
      properties:
        name:
          type: string
          description: |
            Free-form group name. Group name is unique on the given hierarchy level.
        description:
          type: string
          description: Group description, free form text.
        metadata:
          type: object
          description: Arbitrary, object-encoded group's data.
    GroupResSchema:
      type: object
      properties:
        id:
          type: string
          format: ulid
          description: Unique group identifier generated by the service.
        name:
          type: string
          description: Free-form group name.
        parent_id:
          type: string
          description: Group ID of parent group.
        owner_id:
          type: string
          format: uuid
          description: UUID of user that created the group.
        metadata:
          type: object
          description: Arbitrary, object-encoded group's data.
        level:
          type: integer
          description: Level in hierarchy, distance from the root group.
        path:
          type: string
          description: Hierarchy path, concatenated ids of group ancestors.
        children:
          type: object
          # schema: GroupResSchema
        created_at:
          type: string
          description: Datetime of group creation.
        updated_at:
          type: string
          description: Datetime of last group updated.
      required:
        - id
        - name
        - owner_id
        - description
        - level
        - path
        - created_at
        - updated_at
    MembersReqSchema:
      type: object
      properties:
        members:
          type: array
          minItems: 0
          uniqueItems: true
          items:
            type: string
            format: uuid | ulid
        type:
          type: string
          description: Type of entity
    ShareGroupAccessReqSchema:
      type: object
      properties:
        thing_group_id:
          type: string
          description: Group ID of the Thing Group.
          format: uuid
    GroupsPage:
      type: object
      properties:
        groups:
          type: array
          minItems: 0
          uniqueItems: true
          items:
            $ref: "#/components/schemas/GroupResSchema"
        total:
          type: integer
          description: Total number of items.
        level:
          type: integer
          description: Level of hierarchy up to which groups are fetched.
      required:
        - groups
        - total
        - level
    MembershipPage:
      type: object
      properties:
        groups:
          type: array
          minItems: 0
          uniqueItems: true
          items:
            $ref: "#/components/schemas/GroupResSchema"
        offset:
          type: integer
          description: Number of items to skip during retrieval.
        limit:
          type: integer
          description: Maximum number of items to return in one page.
        total:
          type: integer
          description: Total number of items.
      required:
        - groups
    PoliciesReqSchema:
      type: object
      properties:
        object:
          type: string
          description: |
            Specifies an object field for the field.
            Object indicates application objects such as ThingID.
        subjects:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
        policies:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string

  parameters:
    ApiKeyId:
      name: id
      description: API Key ID.
      in: path
      schema:
        type: string
        format: uuid
      required: true
    UserGroupID:
      name: userGroupID
      description: User Group ID.
      in: path
      schema:
        type: string
        format: uuid
      required: true
    GroupId:
      name: groupId
      description: Group ID.
      in: path
      schema:
        type: string
        format: uuid
      required: true
    MemberId:
      name: memberId
      description: Member id.
      in: path
      schema:
        type: string
        format: uuid | ulid
      required: true
    Limit:
      name: limit
      description: Size of the subset to retrieve.
      in: query
      schema:
        type: integer
        default: 10
        maximum: 100
        minimum: 1
      required: false
    Offset:
      name: offset
      description: Number of items to skip during retrieval.
      in: query
      schema:
        type: integer
        default: 0
        minimum: 0
      required: false
    Level:
      name: level
      description: Level of hierarchy up to which to retrieve groups from given group id.
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 5
      required: false
    Metadata:
      name: metadata
      description: Metadata filter. Filtering is performed matching the parameter with metadata on top level. Parameter is json.
      in: query
      required: false
      schema:
        type: object
        additionalProperties: {}
    Tree:
      name: tree
      description: Specify type of response, JSON array or tree.
      in: query
      required: false
      schema:
        type: boolean
        default: false

  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.
              duration:
                type: number
                format: integer
                example: 23456
                description: Number of seconds issued token is valid for.
    GroupCreateReq:
      description: JSON-formatted document describing group create request.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GroupReqSchema"
    GroupUpdateReq:
      description: JSON-formatted document describing group create request.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GroupUpdateSchema"
    MembersReq:
      description: JSON array of member IDs.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MembersReqSchema"
    ShareGroupAccessReq:
      description: test
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ShareGroupAccessReqSchema"
    PoliciesReq:
      description: JSON-formatted document describing adding policies request.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PoliciesReqSchema"

  responses:
    ServiceError:
      description: Unexpected server-side error occurred.
    KeyRes:
      description: Data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Key"
    GroupCreateRes:
      description: Group created.
      headers:
        Location:
          content:
            text/plain:
              schema:
                type: string
                description: Created group's relative URL.
                example: /groups/{groupId}
    ShareAccessRightRes:
      description: User group shared with thing group.
    GroupRes:
      description: Data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GroupResSchema"
    GroupsPageRes:
      description: Group data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GroupsPage"
    MembersRes:
      description: Groups data retrieved. Groups assigned to a member.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MembershipPage"
    MembershipPageRes:
      description: Groups data retrieved. Groups assigned to a member.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MembershipPage"
    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: []