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

openapi: 3.0.3
info:
  title: Magistrala Clients Service
  description: |
    This is the Clients Server based on the OpenAPI 3.0 specification.  It is the HTTP API for managing platform clients. You can now help us improve the API whether it's by making changes to the definition itself or to the code.
    Some useful links:
    - [The Magistrala repository](https://github.com/absmach/magistrala)
  contact:
    email: info@absmach.eu
  license:
    name: Apache 2.0
    url: https://github.com/absmach/magistrala/blob/main/LICENSE
  version: 0.18.0

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

tags:
  - name: Clients
    description: CRUD operations for your clients
    externalDocs:
      description: Find out more about clients
      url: https://magistrala.absmach.eu/docs/
  - name: Roles
    description: All operations involving roles for clients
    externalDocs:
      description: Find out more about roles
      url: https://magistrala.absmach.eu/docs/
  - name: Health
    description: Health check operations
    externalDocs:
      description: Find out more about health checks
      url: https://magistrala.absmach.eu/docs/

paths:
  /{domainID}/clients:
    post:
      operationId: createClient
      tags:
        - Clients
      summary: Adds new client
      description: |
        Adds new client to the list of clients owned by user identified using
        the provided access token.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
      requestBody:
        $ref: "#/components/requestBodies/ClientCreateReq"
      responses:
        "201":
          $ref: "#/components/responses/ClientCreateRes"
        "400":
          description: Failed due to malformed JSON.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "409":
          description: Failed due to using an existing identity.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    get:
      operationId: listClients
      tags:
        - Clients
      summary: Retrieves clients
      description: |
        Retrieves a list of clients. Due to performance concerns, data
        is retrieved in subsets. The API clients must ensure that the entire
        dataset is consumed either by making subsequent requests, or by
        increasing the subset size of the initial request.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Order"
        - $ref: "#/components/parameters/Direction"
        - $ref: "#/components/parameters/Metadata"
        - $ref: "#/components/parameters/Status"
        - $ref: "#/components/parameters/ClientName"
        - $ref: "#/components/parameters/Tags"
        - $ref: "#/components/parameters/ID"
        - $ref: "./schemas/roles.yaml#/components/parameters/ActionsQuery"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleIDQuery"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleNameQuery"
        - $ref: "#/components/parameters/AccessType"
        - $ref: "#/components/parameters/OnlyTotal"
        - $ref: "#/components/parameters/Channel"
        - $ref: "#/components/parameters/ConnectionType"
        - $ref: "#/components/parameters/Group"
        - $ref: "#/components/parameters/User"
        - $ref: "#/components/parameters/CreatedFrom"
        - $ref: "#/components/parameters/CreatedTo"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/ClientPageRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/bulk:
    post:
      operationId: bulkCreateClients
      summary: Bulk provisions new clients
      description: |
        Adds a list of new clients to the list of clients owned by user identified using
        the provided access token.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
      tags:
        - Clients
      requestBody:
        $ref: "#/components/requestBodies/ClientsCreateReq"
      responses:
        "200":
          $ref: "#/components/responses/ClientPageRes"
        "400":
          description: Failed due to malformed JSON.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}:
    get:
      operationId: getClient
      summary: Retrieves client info
      description: |
        Retrieves a specific client that is identified by the client ID.
      tags:
        - Clients
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/ClientRes"
        "400":
          description: Failed due to malformed domain ID.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    patch:
      operationId: updateClient
      summary: Updates name, metadata, and private metadata of the client.
      description: |
        Update is performed by replacing the current resource data with values
        provided in a request payload. Note that the client's type and ID
        cannot be changed.
      tags:
        - Clients
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
      requestBody:
        $ref: "#/components/requestBodies/ClientUpdateReq"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/ClientRes"
        "400":
          description: Failed due to malformed JSON.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: Failed due to non existing client.
        "409":
          description: Failed due to using an existing identity.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"
    delete:
      summary: Delete client for a client with the given id.
      description: |
        Delete client removes a client with the given id from repo
        and removes all the policies related to this client.
      tags:
        - Clients
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Client deleted.
        "400":
          description: Failed due to malformed domain ID.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Unauthorized access to client id.
        "404":
          description: Missing client.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/tags:
    patch:
      operationId: updateClientTags
      summary: Updates tags the client.
      description: |
        Updates tags of the client with provided ID. Tags is updated using
        authorization token and the new tags received in request.
      tags:
        - Clients
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
      requestBody:
        $ref: "#/components/requestBodies/ClientUpdateTagsReq"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/ClientRes"
        "400":
          description: Failed due to malformed JSON.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: Failed due to non existing client.
        "401":
          description: Missing or invalid access token provided.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/secret:
    patch:
      operationId: updateClientSecret
      summary: Updates Secret of the identified client.
      description: |
        Updates secret of the identified in client. Secret is updated using
        authorization token and the new received info. Update is performed by replacing current key with a new one.
      tags:
        - Clients
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
      requestBody:
        $ref: "#/components/requestBodies/ClientUpdateSecretReq"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/ClientRes"
        "400":
          description: Failed due to malformed JSON.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: Failed due to non existing client.
        "409":
          description: Specified key already exists.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/disable:
    post:
      operationId: disableClient
      summary: Disables a client
      description: |
        Disables a specific client that is identified by the client ID.
      tags:
        - Clients
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/DisabledClientRes"
        "400":
          description: Failed due to malformed client's ID.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "409":
          description: Failed due to already disabled client.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/enable:
    post:
      operationId: enableClient
      summary: Enables a client
      description: |
        Enables a specific client that is identified by the client ID.
      tags:
        - Clients
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/ClientRes"
        "400":
          description: Failed due to malformed client's ID.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "409":
          description: Failed due to already enabled client.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/parent:
    post:
      operationId: setClientParentGroup
      summary: Sets a parent group for a client
      description: |
        Sets a parent group for a specific client that is identified by the client ID.
      tags:
        - Clients
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
      requestBody:
        $ref: "#/components/requestBodies/ClientParentGroupReq"
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Parent group set.
        "400":
          description: Failed due to malformed client's ID.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    delete:
      operationId: removeClientParentGroup
      summary: Removes a parent group from a client.
      description: |
        Removes a parent group from a specific client that is identified by the client ID.
      tags:
        - Clients
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
      requestBody:
        $ref: "#/components/requestBodies/ClientParentGroupReq"
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Parent group removed.
        "400":
          description: Failed due to malformed client's ID.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/roles:
    post:
      operationId: createClientRole
      summary: Creates a role for a client
      description: |
        Creates a role for a specific client that is identified by the client ID.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
      requestBody:
        $ref: "./schemas/roles.yaml#/components/requestBodies/CreateRoleReq"
      security:
        - bearerAuth: []
      responses:
        "201":
          $ref: "./schemas/roles.yaml#/components/responses/CreateRoleRes"
        "400":
          description: Failed due to malformed client's ID.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    get:
      operationId: listClientRoles
      tags:
        - Roles
      summary: Retrieves clients roles.
      description: |
        Retrieves a list of client roles. Due to performance concerns, data
        is retrieved in subsets. The API clients must ensure that the entire
        dataset is consumed either by making subsequent requests, or by
        increasing the subset size of the initial request.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/ListRolesRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/roles/members:
    get:
      operationId: getClientMembers
      tags:
        - Roles
      summary: Retrieves client members from all roles.
      description: |
        Retrieves members from role for the specific client.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/ListEntityMembersRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/roles/{roleID}:
    get:
      operationId: getClientRole
      tags:
        - Roles
      summary: Retrieves client role.
      description: |
        Retrieves a specific client role that is identified by the role name.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/GetRoleRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    put:
      operationId: updateClientRole
      summary: Updates client role.
      description: |
        Updates a specific client role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      requestBody:
        $ref: "./schemas/roles.yaml#/components/requestBodies/UpdateRoleReq"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/GetRoleRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    delete:
      operationId: deleteClientRole
      summary: Deletes client role.
      description: |
        Deletes a specific client role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Role deleted.
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/roles/{roleID}/actions:
    post:
      operationId: addClientRoleAction
      summary: Adds a role action for a client role.
      description: |
        Adds a role action for a specific client role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      requestBody:
        $ref: "./schemas/roles.yaml#/components/requestBodies/AddRoleActionsReq"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/AddRoleActionsRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    get:
      operationId: listClientRoleActions
      tags:
        - Roles
      summary: Lists client role actions.
      description: |
        Retrieves a list of client role actions.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/ListRoleActionsRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/roles/{roleID}/actions/delete:
    post:
      operationId: deleteClientRoleAction
      summary: Deletes role actions for a client role.
      description: |
        Deletes a role action for a specific client role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      requestBody:
        $ref: "./schemas/roles.yaml#/components/requestBodies/AddRoleActionsReq"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Role actions deleted.
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/roles/{roleID}/actions/delete-all:
    post:
      operationId: deleteAllClientRoleActions
      summary: Deletes all role actions for a client role.
      description: |
        Deletes all role actions for a specific client role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: All role actions deleted.
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/roles/{roleID}/members:
    post:
      operationId: addClientRoleMember
      summary: Adds a member to a client role.
      description: |
        Adds a member to a specific client role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      requestBody:
        $ref: "./schemas/roles.yaml#/components/requestBodies/AddRoleMembersReq"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/AddRoleMembersRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    get:
      operationId: listClientRoleMembers
      tags:
        - Roles
      summary: Lists client role members.
      description: |
        Retrieves a list of client role members.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/ListRoleMembersRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/roles/{roleID}/members/delete:
    post:
      operationId: deleteClientRoleMembers
      summary: Deletes members from a client role.
      description: |
        Deletes a member from a specific client role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      requestBody:
        $ref: "./schemas/roles.yaml#/components/requestBodies/AddRoleMembersReq"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Role members deleted.
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/{clientID}/roles/{roleID}/members/delete-all:
    post:
      operationId: deleteAllClientRoleMembers
      summary: Deletes all members from a client role.
      description: |
        Deletes all members from a specific client role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/clientID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: All role members deleted.
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/clients/roles/available-actions:
    get:
      operationId: listAvailableActions
      tags:
        - Roles
      summary: Retrieves available actions.
      description: |
        Retrieves a list of available actions.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/ListAvailableActionsRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /health:
    get:
      summary: Retrieves service health check info.
      tags:
        - Health
      security: []
      responses:
        "200":
          $ref: "#/components/responses/HealthRes"
        "500":
          $ref: "#/components/responses/ServiceError"

components:
  schemas:
    ClientReqObj:
      type: object
      properties:
        name:
          type: string
          example: clientName
          description: Client name.
        tags:
          type: array
          minItems: 0
          items:
            type: string
          example: ["tag1", "tag2"]
          description: Client tags.
        credentials:
          type: object
          properties:
            identity:
              type: string
              example: "clientIDentity"
              description: Client's identity will be used as its unique identifier
            secret:
              type: string
              format: password
              example: bb7edb32-2eac-4aad-aebe-ed96fe073879
              minimum: 8
              description: Free-form account secret used for acquiring auth token(s).
        private_metadata:
          type: object
          example: { "model": "example" }
          description: Arbitrary, object-encoded client's data private to the client.
        metadata:
          type: object
          example: { "model": "example" }
          description: Arbitrary, object-encoded client's data visible to other clients.
        status:
          type: string
          description: Client Status
          format: string
          example: enabled
      required:
        - credentials

    ParentGroupReqObj:
      type: object
      properties:
        parent_group_id:
          type: string
          format: uuid
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: Parent group unique identifier.
      required:
        - parent_group_id

    Client:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: Client unique identifier.
        name:
          type: string
          example: clientName
          description: Client name.
        tags:
          type: array
          minItems: 0
          items:
            type: string
          example: ["tag1", "tag2"]
          description: Client tags.
        domain_id:
          type: string
          format: uuid
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: ID of the domain to which client belongs.
        credentials:
          type: object
          properties:
            identity:
              type: string
              example: clientIDentity
              description: Client Identity for example email address.
            secret:
              type: string
              example: bb7edb32-2eac-4aad-aebe-ed96fe073879
              description: Client secret password.
        private_metadata:
          type: object
          example: { "model": "example" }
          description: Arbitrary, object-encoded client's data private to the client.
        metadata:
          type: object
          example: { "model": "example" }
          description: Arbitrary, object-encoded client's data visible to other clients.
        status:
          type: string
          description: Client Status
          format: string
          example: enabled
        created_at:
          type: string
          format: date-time
          example: "2019-11-26 13:31:52"
          description: Time when the channel was created.
        updated_at:
          type: string
          format: date-time
          example: "2019-11-26 13:31:52"
          description: Time when the channel was created.
      xml:
        name: client

    ClientWithEmptySecret:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: Client unique identifier.
        name:
          type: string
          example: clientName
          description: Client name.
        tags:
          type: array
          minItems: 0
          items:
            type: string
          example: ["tag1", "tag2"]
          description: Client tags.
        domain_id:
          type: string
          format: uuid
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: ID of the domain to which client belongs.
        credentials:
          type: object
          properties:
            identity:
              type: string
              example: clientIDentity
              description: Client Identity for example email address.
            secret:
              type: string
              example: ""
              description: Client secret password.
        private_metadata:
          type: object
          example: { "model": "example" }
          description: Arbitrary, object-encoded client's data private to the client.
        metadata:
          type: object
          example: { "model": "example" }
          description: Arbitrary, object-encoded client's data visible to other clients.
        status:
          type: string
          description: Client Status
          format: string
          example: enabled
        created_at:
          type: string
          format: date-time
          example: "2019-11-26 13:31:52"
          description: Time when the channel was created.
        updated_at:
          type: string
          format: date-time
          example: "2019-11-26 13:31:52"
          description: Time when the channel was created.
      xml:
        name: client

    ClientsPage:
      type: object
      properties:
        clients:
          type: array
          minItems: 0
          uniqueItems: true
          items:
            $ref: "#/components/schemas/ClientWithEmptySecret"
        total:
          type: integer
          example: 1
          description: Total number of items.
        offset:
          type: integer
          description: Number of items to skip during retrieval.
        limit:
          type: integer
          example: 10
          description: Maximum number of items to return in one page.
      required:
        - total

    ClientUpdate:
      type: object
      properties:
        name:
          type: string
          example: clientName
          description: Client name.
        metadata:
          type: object
          example: { "role": "general" }
          description: Arbitrary, object-encoded client's data visible to other clients.
        private_metadata:
          type: object
          example: { "role": "general" }
          description: Arbitrary, object-encoded client's data private to the client.
      required:
        - name
        - private_metadata
        - metadata

    ClientTags:
      type: object
      properties:
        tags:
          type: array
          example: ["tag1", "tag2"]
          description: Client tags.
          minItems: 0
          uniqueItems: true
          items:
            type: string

    DisabledClient:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: Client unique identifier.
        name:
          type: string
          example: clientName
          description: Client name.
        tags:
          type: array
          minItems: 0
          items:
            type: string
          example: ["tag1", "tag2"]
          description: Client tags.
        domain_id:
          type: string
          format: uuid
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: ID of the domain to which client belongs.
        credentials:
          type: object
          properties:
            identity:
              type: string
              example: clientIDentity
              description: Client Identity for example email address.
            secret:
              type: string
              example: bb7edb32-2eac-4aad-aebe-ed96fe073879
              description: Client secret password.
        metadata:
          type: object
          example: { "model": "example" }
          description: Arbitrary, object-encoded client's data visible to other clients.
        status:
          type: string
          description: Client Status
          format: string
          example: disabled
        created_at:
          type: string
          format: date-time
          example: "2019-11-26 13:31:52"
          description: Time when the channel was created.
        updated_at:
          type: string
          format: date-time
          example: "2019-11-26 13:31:52"
          description: Time when the channel was created.
      xml:
        name: client

    ClientSecret:
      type: object
      properties:
        secret:
          type: string
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: New client secret.
      required:
        - secret

    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example: { "error": "malformed entity specification" }

    HealthRes:
      type: object
      properties:
        status:
          type: string
          description: Service status.
          enum:
            - pass
        version:
          type: string
          description: Service version.
          example: 0.14.0
        commit:
          type: string
          description: Service commit hash.
          example: 7d6f4dc4f7f0c1fa3dc24eddfb18bb5073ff4f62
        description:
          type: string
          description: Service description.
          example: clients service
        build_time:
          type: string
          description: Service build time.
          example: 1970-01-01_00:00:00

  parameters:
    clientID:
      name: clientID
      description: Unique client identifier.
      in: path
      schema:
        type: string
        format: uuid
        minLength: 36
        maxLength: 36
        pattern: "^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
      required: true
      example: bb7edb32-2eac-4aad-aebe-ed96fe073879

    ClientName:
      name: name
      description: Client's name.
      in: query
      schema:
        type: string
      required: false
      example: "clientName"

    Status:
      name: status
      description: Client account status.
      in: query
      schema:
        type: string
        default: enabled
      required: false
      example: enabled

    Tags:
      name: tags
      description: Clients tags. Multiple tags can be specified separated by comma for OR condition and plus for AND condition.
      in: query
      schema:
        type: string
      required: false
      example: "orange,yellow"

    Metadata:
      name: metadata
      description: Metadata filter. Filtering is performed matching the parameter with metadata on top level. Parameter is json.
      in: query
      schema:
        type: string
      required: false

    Limit:
      name: limit
      description: Size of the subset to retrieve.
      in: query
      schema:
        type: integer
        default: 10
        maximum: 100
        minimum: 1
      required: false
      example: 100

    Offset:
      name: offset
      description: Number of items to skip during retrieval.
      in: query
      schema:
        type: integer
        default: 0
        minimum: 0
      required: false
      example: 0

    Order:
      name: order
      description: Field by which to order the results
      in: query
      schema:
        type: string
      required: false
      example: created_at

    Direction:
      name: dir
      description: Direction of ordering the results.
      in: query
      schema:
        type: string
        enum:
          - asc
          - desc
      required: false
      example: desc

    ID:
      name: id
      description: List clients with the given ID.
      in: query
      schema:
        type: string
        format: uuid
      required: false
      example: bb7edb32-2eac-4aad-aebe-ed96fe073879

    AccessType:
      name: access_type
      description: Type of access the user has on the client.
      in: query
      schema:
        type: string
        enum:
          - direct
          - domain
          - indirect
          - indirect_group
      required: false
      example: direct

    OnlyTotal:
      name: only_total
      description: If true, the response will contain only the total number of clients that match the query parameters.
      in: query
      schema:
        type: boolean
        default: false
      required: false

    Channel:
      name: channel
      description: If provided lists clients connected to a channel with the provided ID.
      in: query
      schema:
        type: string
        format: uuid
        minLength: 36
      required: false
      example: bb7edb32-2eac-4aad-aebe-ed96fe073879

    ConnectionType:
      name: connection_type
      description: If provided with channel parameter lists clients connected to the channel with the provided connection type.
      in: query
      schema:
        type: string
        enum:
          - Publish
          - Subscribe
      required: false
      example: Publish

    Group:
      name: group
      description: If provided lists clients belonging to a group with the provided ID.
      in: query
      schema:
        type: string
        format: uuid
        minLength: 36
      required: false
      example: bb7edb32-2eac-4aad-aebe-ed96fe073879

    User:
      name: user
      description: If provided lists clients associated with a user with the provided ID. Only available for admin users.
      in: query
      schema:
        type: string
        format: uuid
        minLength: 36
      required: false
      example: bb7edb32-2eac-4aad-aebe-ed96fe073879
    
    CreatedFrom:
      name: created_from
      description: Filter clients created from this date (inclusive).
      in: query
      schema:
        type: string
        format: date-time
      required: false
      example: "2023-01-01T00:00:00Z"

    CreatedTo:
      name: created_to
      description: Filter clients created up to this date (inclusive).
      in: query
      schema:
        type: string
        format: date-time
      required: false
      example: "2023-12-31T23:59:59Z"

  requestBodies:
    ClientCreateReq:
      description: JSON-formatted document describing the new client to be registered
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ClientReqObj"

    ClientsCreateReq:
      description: JSON-formatted document describing the new clients.
      required: true
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/ClientReqObj"

    ClientUpdateReq:
      description: JSON-formated document describing the metadata, private metadata and name of client to be update
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ClientUpdate"

    ClientUpdateTagsReq:
      description: JSON-formated document describing the tags of client to be update
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ClientTags"

    ClientUpdateSecretReq:
      description: Secret change data. Client can change its secret.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ClientSecret"

    ClientParentGroupReq:
      description: JSON-formated document describing the parent group to be set to or removed from a client.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ParentGroupReqObj"

  responses:
    ClientCreateRes:
      description: Registered new client.
      headers:
        Location:
          schema:
            type: string
            format: url
          description: Registered client relative URL in the format `clients/<client_id>`
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Client"
      links:
        get:
          operationId: getClient
          parameters:
            clientID: $response.body#/id
        update:
          operationId: updateClient
          parameters:
            clientID: $response.body#/id
        update_tags:
          operationId: updateClientTags
          parameters:
            clientID: $response.body#/id
        update_secret:
          operationId: updateClientSecret
          parameters:
            clientID: $response.body#/id
        disable:
          operationId: disableClient
          parameters:
            clientID: $response.body#/id
        enable:
          operationId: enableClient
          parameters:
            clientID: $response.body#/id

    ClientRes:
      description: Data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Client"

    DisabledClientRes:
      description: Data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DisabledClient"

    ClientPageRes:
      description: Data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ClientsPage"

    ClientsPageRes:
      description: Data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ClientsPage"

    HealthRes:
      description: Service Health Check.
      content:
        application/health+json:
          schema:
            $ref: "#/components/schemas/HealthRes"

    ServiceError:
      description: Unexpected server-side error occurred.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

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

security:
  - bearerAuth: []
