mirror of
https://github.com/absmach/supermq.git
synced 2026-06-23 06:30:22 +00:00
Dušan Borovčanin
2057 lines
61 KiB
YAML
2057 lines
61 KiB
YAML
# Copyright (c) Abstract Machines
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
|
|
openapi: 3.0.3
|
|
info:
|
|
title: Magistrala Users Service
|
|
description: |
|
|
This is the Users Server based on the OpenAPI 3.0 specification. It is the HTTP API for managing platform users. 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@abstractmachines.fr
|
|
license:
|
|
name: Apache 2.0
|
|
url: https://github.com/absmach/magistrala/blob/main/LICENSE
|
|
version: 0.14.0
|
|
|
|
servers:
|
|
- url: http://localhost:9002
|
|
- url: https://localhost:9002
|
|
|
|
tags:
|
|
- name: Users
|
|
description: Everything about your Users
|
|
externalDocs:
|
|
description: Find out more about users
|
|
url: https://docs.magistrala.abstractmachines.fr/
|
|
- name: Groups
|
|
description: Everything about your Groups
|
|
externalDocs:
|
|
description: Find out more about users groups
|
|
url: https://docs.magistrala.abstractmachines.fr/
|
|
|
|
paths:
|
|
/users:
|
|
post:
|
|
operationId: createUser
|
|
tags:
|
|
- Users
|
|
summary: Registers user account
|
|
description: |
|
|
Registers new user account given email and password. New account will
|
|
be uniquely identified by its email address.
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/UserCreateReq"
|
|
responses:
|
|
"201":
|
|
$ref: "#/components/responses/UserCreateRes"
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"403":
|
|
description: Failed to perform authorization over the entity.
|
|
"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: listUsers
|
|
tags:
|
|
- Users
|
|
summary: List users
|
|
description: |
|
|
Retrieves a list of users. Due to performance concerns, data
|
|
is retrieved in subsets. The API 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: "#/components/parameters/Limit"
|
|
- $ref: "#/components/parameters/Offset"
|
|
- $ref: "#/components/parameters/Metadata"
|
|
- $ref: "#/components/parameters/Status"
|
|
- $ref: "#/components/parameters/UserName"
|
|
- $ref: "#/components/parameters/UserIdentity"
|
|
- $ref: "#/components/parameters/Tags"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/UserPageRes"
|
|
"400":
|
|
description: Failed due to malformed query parameters.
|
|
"401":
|
|
description: |
|
|
Missing or invalid access token provided.
|
|
This endpoint is available only for administrators.
|
|
"404":
|
|
description: A non-existent entity request.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/users/profile:
|
|
get:
|
|
operationId: getProfile
|
|
summary: Gets info on currently logged in user.
|
|
description: |
|
|
Gets info on currently logged in user. Info is obtained using
|
|
authorization token
|
|
tags:
|
|
- Users
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/UserRes"
|
|
"400":
|
|
description: Failed due to malformed query parameters.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/users/{userID}:
|
|
get:
|
|
operationId: getUser
|
|
summary: Retrieves a user
|
|
description: |
|
|
Retrieves a specific user that is identifier by the user ID.
|
|
tags:
|
|
- Users
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserID"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/UserRes"
|
|
"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"
|
|
|
|
patch:
|
|
operationId: updateUser
|
|
summary: Updates name and metadata of the user.
|
|
description: |
|
|
Updates name and metadata of the user with provided ID. Name and metadata
|
|
is updated using authorization token and the new received info.
|
|
tags:
|
|
- Users
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserID"
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/UserUpdateReq"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/UserRes"
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"403":
|
|
description: Failed to perform authorization over the entity.
|
|
"404":
|
|
description: Failed due to non existing user.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"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"
|
|
|
|
/users/{userID}/tags:
|
|
patch:
|
|
operationId: updateUserTags
|
|
summary: Updates tags the user.
|
|
description: |
|
|
Updates tags of the user with provided ID. Tags is updated using
|
|
authorization token and the new tags received in request.
|
|
tags:
|
|
- Users
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserID"
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/UserUpdateTagsReq"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/UserRes"
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"403":
|
|
description: Failed to perform authorization over the entity.
|
|
"404":
|
|
description: Failed due to non existing user.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/users/{userID}/identity:
|
|
patch:
|
|
operationId: updateUserIdentity
|
|
summary: Updates Identity of the user.
|
|
description: |
|
|
Updates identity of the user with provided ID. Identity is
|
|
updated using authorization token and the new received identity.
|
|
tags:
|
|
- Users
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserID"
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/UserUpdateIdentityReq"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/UserRes"
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"403":
|
|
description: Failed to perform authorization over the entity.
|
|
"404":
|
|
description: Failed due to non existing user.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"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"
|
|
|
|
/users/{userID}/role:
|
|
patch:
|
|
operationId: updateUserRole
|
|
summary: Updates the user role.
|
|
description: |
|
|
Updates role for the user with provided ID.
|
|
tags:
|
|
- Users
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserID"
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/UserUpdateRoleReq"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/UserRes"
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"403":
|
|
description: Failed to perform authorization over the entity.
|
|
"404":
|
|
description: Failed due to non existing user.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/users/{userID}/disable:
|
|
post:
|
|
operationId: disableUser
|
|
summary: Disables a user
|
|
description: |
|
|
Disables a specific user that is identifier by the user ID.
|
|
tags:
|
|
- Users
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserID"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/UserRes"
|
|
"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.
|
|
"409":
|
|
description: Failed due to already disabled user.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/users/{userID}/enable:
|
|
post:
|
|
operationId: enableUser
|
|
summary: Enables a user
|
|
description: |
|
|
Enables a specific user that is identifier by the user ID.
|
|
tags:
|
|
- Users
|
|
parameters:
|
|
- $ref: "#/components/parameters/UserID"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/UserRes"
|
|
"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.
|
|
"409":
|
|
description: Failed due to already enabled user.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/users/secret:
|
|
patch:
|
|
operationId: updateUserSecret
|
|
summary: Updates Secret of currently logged in user.
|
|
description: |
|
|
Updates secret of currently logged in user. Secret is updated using
|
|
authorization token and the new received info.
|
|
tags:
|
|
- Users
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/UserUpdateSecretReq"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/UserRes"
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"404":
|
|
description: Failed due to non existing user.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/password/reset-request:
|
|
post:
|
|
operationId: requestPasswordReset
|
|
summary: User password reset request
|
|
description: |
|
|
Generates a reset token and sends and
|
|
email with link for resetting password.
|
|
tags:
|
|
- Users
|
|
parameters:
|
|
- $ref: "#/components/parameters/Referer"
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/RequestPasswordReset"
|
|
responses:
|
|
"201":
|
|
description: Users link for resetting password.
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"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"
|
|
|
|
/password/reset:
|
|
put:
|
|
operationId: resetPassword
|
|
summary: User password reset endpoint
|
|
description: |
|
|
When user gets reset token, after he submitted
|
|
email to `/password/reset-request`, posting a
|
|
new password along to this endpoint will change password.
|
|
tags:
|
|
- Users
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/PasswordReset"
|
|
responses:
|
|
"201":
|
|
description: User link .
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/groups/{groupID}/users:
|
|
get:
|
|
operationId: listUsersInGroup
|
|
tags:
|
|
- Users
|
|
summary: List users in a group
|
|
description: |
|
|
Retrieves a list of users in a group. Due to performance concerns, data
|
|
is retrieved in subsets. The API 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: "#/components/parameters/GroupID"
|
|
- $ref: "#/components/parameters/Limit"
|
|
- $ref: "#/components/parameters/Offset"
|
|
- $ref: "#/components/parameters/Level"
|
|
- $ref: "#/components/parameters/Tree"
|
|
- $ref: "#/components/parameters/Metadata"
|
|
- $ref: "#/components/parameters/GroupName"
|
|
- $ref: "#/components/parameters/ParentID"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/MembersPageRes"
|
|
"400":
|
|
description: Failed due to malformed query parameters.
|
|
"401":
|
|
description: |
|
|
Missing or invalid access token provided.
|
|
This endpoint is available only for administrators.
|
|
"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"
|
|
|
|
/channels/{channelID}/users:
|
|
get:
|
|
operationId: listUsersInChannel
|
|
tags:
|
|
- Users
|
|
summary: List users in a channel
|
|
description: |
|
|
Retrieves a list of users in a channel. Due to performance concerns, data
|
|
is retrieved in subsets. The API 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: "#/components/parameters/ChannelID"
|
|
- $ref: "#/components/parameters/Limit"
|
|
- $ref: "#/components/parameters/Offset"
|
|
- $ref: "#/components/parameters/Level"
|
|
- $ref: "#/components/parameters/Tree"
|
|
- $ref: "#/components/parameters/Metadata"
|
|
- $ref: "#/components/parameters/ChannelName"
|
|
- $ref: "#/components/parameters/ParentID"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/MembersPageRes"
|
|
"400":
|
|
description: Failed due to malformed query parameters.
|
|
"401":
|
|
description: |
|
|
Missing or invalid access token provided.
|
|
This endpoint is available only for administrators.
|
|
"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"
|
|
|
|
/users/tokens/issue:
|
|
post:
|
|
operationId: issueToken
|
|
summary: Issue Token
|
|
description: |
|
|
Issue Access and Refresh Token used for authenticating into the system.
|
|
tags:
|
|
- Users
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/IssueTokenReq"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/TokenRes"
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"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"
|
|
|
|
/users/tokens/refresh:
|
|
post:
|
|
operationId: refreshToken
|
|
summary: Refresh Token
|
|
description: |
|
|
Refreshes Access and Refresh Token used for authenticating into the system.
|
|
tags:
|
|
- Users
|
|
security:
|
|
- refreshAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/TokenRes"
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"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"
|
|
|
|
/groups:
|
|
post:
|
|
operationId: createGroup
|
|
tags:
|
|
- Groups
|
|
summary: Creates new group
|
|
description: |
|
|
Creates new group that can be used for grouping entities. New account will
|
|
be uniquely identified by its identity.
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/GroupCreateReq"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"201":
|
|
$ref: "#/components/responses/GroupCreateRes"
|
|
"400":
|
|
description: Failed due to malformed JSON.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"403":
|
|
description: Failed to perform authorization over the entity.
|
|
"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: listGroups
|
|
summary: Lists groups.
|
|
description: |
|
|
Lists 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. Due to performance concerns, result
|
|
is returned in subsets.
|
|
tags:
|
|
- Groups
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/Limit"
|
|
- $ref: "#/components/parameters/Offset"
|
|
- $ref: "#/components/parameters/Level"
|
|
- $ref: "#/components/parameters/Tree"
|
|
- $ref: "#/components/parameters/Metadata"
|
|
- $ref: "#/components/parameters/GroupName"
|
|
- $ref: "#/components/parameters/ParentID"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/GroupPageRes"
|
|
"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: Group does not exist.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/groups/{groupID}:
|
|
get:
|
|
operationId: getGroup
|
|
summary: Gets group info.
|
|
description: |
|
|
Gets info on a group specified by id.
|
|
tags:
|
|
- Groups
|
|
parameters:
|
|
- $ref: "#/components/parameters/GroupID"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/GroupRes"
|
|
"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: Group does not exist.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
put:
|
|
operationId: updateGroup
|
|
summary: Updates group data.
|
|
description: |
|
|
Updates Name, Description or Metadata of a group.
|
|
tags:
|
|
- Groups
|
|
parameters:
|
|
- $ref: "#/components/parameters/GroupID"
|
|
security:
|
|
- bearerAuth: []
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/GroupUpdateReq"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/GroupRes"
|
|
"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: Group does not exist.
|
|
"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 group for a group with the given id.
|
|
description: |
|
|
Delete group removes a group with the given id from repo
|
|
and removes all the policies related to this group.
|
|
tags:
|
|
- Groups
|
|
parameters:
|
|
- $ref: "#/components/parameters/GroupID"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"204":
|
|
description: Group deleted.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"403":
|
|
description: Unauthorized access to group id.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/groups/{groupID}/children:
|
|
get:
|
|
operationId: listChildren
|
|
summary: List children of a certain group
|
|
description: |
|
|
Lists 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. Due to performance concerns, result
|
|
is returned in subsets.
|
|
tags:
|
|
- Groups
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/GroupID"
|
|
- $ref: "#/components/parameters/Limit"
|
|
- $ref: "#/components/parameters/Offset"
|
|
- $ref: "#/components/parameters/Level"
|
|
- $ref: "#/components/parameters/Tree"
|
|
- $ref: "#/components/parameters/Metadata"
|
|
- $ref: "#/components/parameters/GroupName"
|
|
- $ref: "#/components/parameters/ParentID"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/GroupPageRes"
|
|
"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: Group does not exist.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/groups/{groupID}/parents:
|
|
get:
|
|
operationId: listParents
|
|
summary: List parents of a certain group
|
|
description: |
|
|
Lists 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. Due to performance concerns, result
|
|
is returned in subsets.
|
|
tags:
|
|
- Groups
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: "#/components/parameters/GroupID"
|
|
- $ref: "#/components/parameters/Limit"
|
|
- $ref: "#/components/parameters/Offset"
|
|
- $ref: "#/components/parameters/Level"
|
|
- $ref: "#/components/parameters/Tree"
|
|
- $ref: "#/components/parameters/Metadata"
|
|
- $ref: "#/components/parameters/GroupName"
|
|
- $ref: "#/components/parameters/ParentID"
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/GroupPageRes"
|
|
"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: Group does not exist.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/groups/{groupID}/enable:
|
|
post:
|
|
operationId: enableGroup
|
|
summary: Enables a group
|
|
description: |
|
|
Enables a specific group that is identifier by the group ID.
|
|
tags:
|
|
- Groups
|
|
parameters:
|
|
- $ref: "#/components/parameters/GroupID"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/GroupRes"
|
|
"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.
|
|
"409":
|
|
description: Failed due to already enabled group.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/groups/{groupID}/disable:
|
|
post:
|
|
operationId: disableGroup
|
|
summary: Disables a group
|
|
description: |
|
|
Disables a specific group that is identifier by the group ID.
|
|
tags:
|
|
- Groups
|
|
parameters:
|
|
- $ref: "#/components/parameters/GroupID"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/GroupRes"
|
|
"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.
|
|
"409":
|
|
description: Failed due to already disabled group.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/groups/{groupID}/users/assign:
|
|
post:
|
|
operationId: assignUser
|
|
summary: Assigns a user to a group
|
|
description: |
|
|
Assigns a specific user to a group that is identifier by the group ID.
|
|
tags:
|
|
- Groups
|
|
parameters:
|
|
- $ref: "#/components/parameters/GroupID"
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/AssignUserReq"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
description: Member assigned.
|
|
"400":
|
|
description: Failed due to malformed group'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.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/groups/{groupID}/users/unassign:
|
|
post:
|
|
operationId: unassignUser
|
|
summary: Unassigns a user to a group
|
|
description: |
|
|
Unassigns a specific user to a group that is identifier by the group ID.
|
|
tags:
|
|
- Groups
|
|
parameters:
|
|
- $ref: "#/components/parameters/GroupID"
|
|
requestBody:
|
|
$ref: "#/components/requestBodies/AssignUserReq"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"204":
|
|
description: Member unassigned.
|
|
"400":
|
|
description: Failed due to malformed group'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.
|
|
"415":
|
|
description: Missing or invalid content type.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/channels/{memberID}/groups:
|
|
get:
|
|
operationId: listGroupsInChannel
|
|
summary: Get group associated with the member
|
|
description: |
|
|
Gets groups associated with the channel member specified by id.
|
|
tags:
|
|
- Groups
|
|
parameters:
|
|
- $ref: "#/components/parameters/MemberID"
|
|
- $ref: "#/components/parameters/Limit"
|
|
- $ref: "#/components/parameters/Offset"
|
|
- $ref: "#/components/parameters/Metadata"
|
|
- $ref: "#/components/parameters/Status"
|
|
- $ref: "#/components/parameters/Tags"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/GroupPageRes"
|
|
"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: Group does not exist.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
/users/{memberID}/groups:
|
|
get:
|
|
operationId: listGroupsByUser
|
|
summary: Get group associated with the member
|
|
description: |
|
|
Gets groups associated with the user member specified by id.
|
|
tags:
|
|
- Groups
|
|
parameters:
|
|
- $ref: "#/components/parameters/MemberID"
|
|
- $ref: "#/components/parameters/Limit"
|
|
- $ref: "#/components/parameters/Offset"
|
|
- $ref: "#/components/parameters/Metadata"
|
|
- $ref: "#/components/parameters/Status"
|
|
- $ref: "#/components/parameters/Tags"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/GroupPageRes"
|
|
"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: Group does not exist.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
/domains/{domainID}/users:
|
|
get:
|
|
summary: List users assigned to domain
|
|
description: |
|
|
List users assigned to domain that is identified by the domain ID.
|
|
tags:
|
|
- Domains
|
|
parameters:
|
|
- $ref: "auth.yml#/components/parameters/DomainID"
|
|
- $ref: "#/components/parameters/Limit"
|
|
- $ref: "#/components/parameters/Offset"
|
|
- $ref: "#/components/parameters/Metadata"
|
|
- $ref: "#/components/parameters/Status"
|
|
security:
|
|
- bearerAuth: []
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/UserPageRes"
|
|
description: List of users assigned to domain.
|
|
"400":
|
|
description: Failed due to malformed domain's ID.
|
|
"401":
|
|
description: Missing or invalid access token provided.
|
|
"403":
|
|
description: Unauthorized access the domain ID.
|
|
"404":
|
|
description: A non-existent entity request.
|
|
"422":
|
|
description: Database can't process request.
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
/health:
|
|
get:
|
|
operationId: health
|
|
summary: Retrieves service health check info.
|
|
tags:
|
|
- health
|
|
responses:
|
|
"200":
|
|
$ref: "#/components/responses/HealthRes"
|
|
"500":
|
|
$ref: "#/components/responses/ServiceError"
|
|
|
|
components:
|
|
schemas:
|
|
UserReqObj:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: userName
|
|
description: User name.
|
|
tags:
|
|
type: array
|
|
minItems: 0
|
|
items:
|
|
type: string
|
|
example: ["tag1", "tag2"]
|
|
description: User tags.
|
|
credentials:
|
|
type: object
|
|
properties:
|
|
identity:
|
|
type: string
|
|
example: "admin@example.com"
|
|
description: User's identity for example email address will be used as its unique identifier
|
|
secret:
|
|
type: string
|
|
format: password
|
|
example: password
|
|
minimum: 8
|
|
description: Free-form account secret used for acquiring auth token(s).
|
|
metadata:
|
|
type: object
|
|
example: { "domain": "example.com" }
|
|
description: Arbitrary, object-encoded user's data.
|
|
status:
|
|
type: string
|
|
description: User Status
|
|
format: string
|
|
example: enabled
|
|
required:
|
|
- credentials
|
|
|
|
GroupReqObj:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: groupName
|
|
description: Free-form group name. Group name is unique on the given hierarchy level.
|
|
description:
|
|
type: string
|
|
example: long group description
|
|
description: Group description, free form text.
|
|
parent_id:
|
|
type: string
|
|
example: bb7edb32-2eac-4aad-aebe-ed96fe073879
|
|
description: Id of parent group, it must be existing group.
|
|
metadata:
|
|
type: object
|
|
example: { "domain": "example.com" }
|
|
description: Arbitrary, object-encoded groups's data.
|
|
status:
|
|
type: string
|
|
description: Group Status
|
|
format: string
|
|
example: enabled
|
|
required:
|
|
- name
|
|
|
|
User:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
example: bb7edb32-2eac-4aad-aebe-ed96fe073879
|
|
description: User unique identifier.
|
|
name:
|
|
type: string
|
|
example: userName
|
|
description: User name.
|
|
tags:
|
|
type: array
|
|
minItems: 0
|
|
items:
|
|
type: string
|
|
example: ["tag1", "tag2"]
|
|
description: User tags.
|
|
credentials:
|
|
type: object
|
|
properties:
|
|
identity:
|
|
type: string
|
|
example: admin@magistrala.com
|
|
description: User Identity for example email address.
|
|
metadata:
|
|
type: object
|
|
example: { "address": "example" }
|
|
description: Arbitrary, object-encoded user's data.
|
|
status:
|
|
type: string
|
|
description: User Status
|
|
format: string
|
|
example: enabled
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
example: "2019-11-26 13:31:52"
|
|
description: Time when the group was created.
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
example: "2019-11-26 13:31:52"
|
|
description: Time when the group was created.
|
|
xml:
|
|
name: user
|
|
|
|
Group:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
example: bb7edb32-2eac-4aad-aebe-ed96fe073879
|
|
description: Unique group identifier generated by the service.
|
|
name:
|
|
type: string
|
|
example: groupName
|
|
description: Free-form group name. Group name is unique on the given hierarchy level.
|
|
domain_id:
|
|
type: string
|
|
format: uuid
|
|
example: bb7edb32-2eac-4aad-aebe-ed96fe073879
|
|
description: ID of the domain to which the group belongs..
|
|
parent_id:
|
|
type: string
|
|
format: uuid
|
|
example: bb7edb32-2eac-4aad-aebe-ed96fe073879
|
|
description: Group parent identifier.
|
|
description:
|
|
type: string
|
|
example: long group description
|
|
description: Group description, free form text.
|
|
metadata:
|
|
type: object
|
|
example: { "role": "general" }
|
|
description: Arbitrary, object-encoded groups's data.
|
|
path:
|
|
type: string
|
|
example: bb7edb32-2eac-4aad-aebe-ed96fe073879.bb7edb32-2eac-4aad-aebe-ed96fe073879
|
|
description: Hierarchy path, concatenated ids of group ancestors.
|
|
level:
|
|
type: integer
|
|
description: Level in hierarchy, distance from the root group.
|
|
format: int32
|
|
example: 2
|
|
maximum: 5
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
example: "2019-11-26 13:31:52"
|
|
description: Datetime when the group was created.
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
example: "2019-11-26 13:31:52"
|
|
description: Datetime when the group was created.
|
|
status:
|
|
type: string
|
|
description: Group Status
|
|
format: string
|
|
example: enabled
|
|
xml:
|
|
name: group
|
|
|
|
Members:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
example: bb7edb32-2eac-4aad-aebe-ed96fe073879
|
|
description: User unique identifier.
|
|
name:
|
|
type: string
|
|
example: userName
|
|
description: User name.
|
|
tags:
|
|
type: array
|
|
minItems: 0
|
|
items:
|
|
type: string
|
|
example: ["computations", "datasets"]
|
|
description: User tags.
|
|
credentials:
|
|
type: object
|
|
properties:
|
|
identity:
|
|
type: string
|
|
example: user@magistrala.com
|
|
description: User Identity for example email address.
|
|
secret:
|
|
type: string
|
|
example: password
|
|
minimum: 8
|
|
description: User secret password.
|
|
metadata:
|
|
type: object
|
|
example: { "role": "general" }
|
|
description: Arbitrary, object-encoded user's data.
|
|
status:
|
|
type: string
|
|
description: User Status
|
|
format: string
|
|
example: enabled
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
example: "2019-11-26 13:31:52"
|
|
description: Time when the group was created.
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
example: "2019-11-26 13:31:52"
|
|
description: Time when the group was created.
|
|
xml:
|
|
name: members
|
|
|
|
UsersPage:
|
|
type: object
|
|
properties:
|
|
users:
|
|
type: array
|
|
minItems: 0
|
|
uniqueItems: true
|
|
items:
|
|
$ref: "#/components/schemas/User"
|
|
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:
|
|
- users
|
|
- total
|
|
- offset
|
|
|
|
GroupsPage:
|
|
type: object
|
|
properties:
|
|
groups:
|
|
type: array
|
|
minItems: 0
|
|
uniqueItems: true
|
|
items:
|
|
$ref: "#/components/schemas/Group"
|
|
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:
|
|
- groups
|
|
- total
|
|
- offset
|
|
|
|
MembersPage:
|
|
type: object
|
|
properties:
|
|
members:
|
|
type: array
|
|
minItems: 0
|
|
uniqueItems: true
|
|
items:
|
|
$ref: "#/components/schemas/Members"
|
|
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:
|
|
- members
|
|
- total
|
|
- level
|
|
|
|
UserUpdate:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: userName
|
|
description: User name.
|
|
metadata:
|
|
type: object
|
|
example: { "role": "general" }
|
|
description: Arbitrary, object-encoded user's data.
|
|
required:
|
|
- name
|
|
- metadata
|
|
|
|
UserTags:
|
|
type: object
|
|
properties:
|
|
tags:
|
|
type: array
|
|
example: ["yello", "orange"]
|
|
description: User tags.
|
|
minItems: 0
|
|
uniqueItems: true
|
|
items:
|
|
type: string
|
|
|
|
UserIdentity:
|
|
type: object
|
|
properties:
|
|
identity:
|
|
type: string
|
|
example: user@magistrala.com
|
|
description: User Identity for example email address.
|
|
required:
|
|
- identity
|
|
|
|
UserSecret:
|
|
type: object
|
|
properties:
|
|
old_secret:
|
|
type: string
|
|
example: oldpassword
|
|
minimum: 8
|
|
description: Old user secret password.
|
|
new_secret:
|
|
type: string
|
|
example: newpassword
|
|
minimum: 8
|
|
description: New user secret password.
|
|
required:
|
|
- old_secret
|
|
- new_secret
|
|
|
|
UserRole:
|
|
type: object
|
|
properties:
|
|
role:
|
|
type: string
|
|
enum: ["admin", "user"]
|
|
example: user
|
|
description: User role example.
|
|
required:
|
|
- role
|
|
|
|
GroupUpdate:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: groupName
|
|
description: Free-form group name. Group name is unique on the given hierarchy level.
|
|
description:
|
|
type: string
|
|
example: long description but not too long
|
|
description: Group description, free form text.
|
|
metadata:
|
|
type: object
|
|
example: { "role": "general" }
|
|
description: Arbitrary, object-encoded groups's data.
|
|
required:
|
|
- name
|
|
- metadata
|
|
- description
|
|
|
|
AssignReqObj:
|
|
type: object
|
|
properties:
|
|
members:
|
|
type: array
|
|
minItems: 0
|
|
items:
|
|
type: string
|
|
description: Members IDs
|
|
example:
|
|
[
|
|
"bb7edb32-2eac-4aad-aebe-ed96fe073879",
|
|
"bb7edb32-2eac-4aad-aebe-ed96fe073879",
|
|
]
|
|
relation:
|
|
type: string
|
|
example: "m_write"
|
|
description: Permission relations.
|
|
member_kind:
|
|
type: string
|
|
example: "user"
|
|
description: Member kind.
|
|
required:
|
|
- members
|
|
- relation
|
|
- member_kind
|
|
|
|
AssignUserReqObj:
|
|
type: object
|
|
properties:
|
|
user_ids:
|
|
type: array
|
|
minItems: 0
|
|
items:
|
|
type: string
|
|
description: User IDs
|
|
example:
|
|
[
|
|
"bb7edb32-2eac-4aad-aebe-ed96fe073879",
|
|
"bb7edb32-2eac-4aad-aebe-ed96fe073879",
|
|
]
|
|
relation:
|
|
type: string
|
|
example: "m_write"
|
|
description: Permission relations.
|
|
required:
|
|
- user_ids
|
|
- relation
|
|
|
|
IssueToken:
|
|
type: object
|
|
properties:
|
|
identity:
|
|
type: string
|
|
example: user@magistrala.com
|
|
description: User Identity for example email address.
|
|
secret:
|
|
type: string
|
|
example: password
|
|
minimum: 8
|
|
description: User secret password.
|
|
required:
|
|
- identity
|
|
- 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.0.1
|
|
commit:
|
|
type: string
|
|
description: Service commit hash.
|
|
example: 7d6f4dc4f7f0c1fa3dc24eddfb18bb5073ff4f62
|
|
description:
|
|
type: string
|
|
description: Service description.
|
|
example: <service_name> service
|
|
build_time:
|
|
type: string
|
|
description: Service build time.
|
|
example: 1970-01-01_00:00:00
|
|
|
|
parameters:
|
|
Referer:
|
|
name: Referer
|
|
description: Host being sent by browser.
|
|
in: header
|
|
schema:
|
|
type: string
|
|
required: true
|
|
|
|
UserID:
|
|
name: userID
|
|
description: Unique user 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
|
|
|
|
UserName:
|
|
name: name
|
|
description: User's name.
|
|
in: query
|
|
schema:
|
|
type: string
|
|
required: false
|
|
example: "userName"
|
|
|
|
UserIdentity:
|
|
name: identity
|
|
description: User's identity.
|
|
in: query
|
|
schema:
|
|
type: string
|
|
pattern: "^[^\u0000-\u001F]*$"
|
|
required: false
|
|
example: "admin@example.com"
|
|
|
|
Status:
|
|
name: status
|
|
description: User account status.
|
|
in: query
|
|
schema:
|
|
type: string
|
|
default: enabled
|
|
required: false
|
|
example: enabled
|
|
|
|
Tags:
|
|
name: tags
|
|
description: User tags.
|
|
in: query
|
|
schema:
|
|
type: array
|
|
minItems: 0
|
|
uniqueItems: true
|
|
items:
|
|
type: string
|
|
required: false
|
|
example: ["yello", "orange"]
|
|
|
|
GroupName:
|
|
name: name
|
|
description: Group's name.
|
|
in: query
|
|
schema:
|
|
type: string
|
|
required: false
|
|
example: "groupName"
|
|
|
|
ChannelName:
|
|
name: name
|
|
description: Channel's name.
|
|
in: query
|
|
schema:
|
|
type: string
|
|
required: false
|
|
example: "channelName"
|
|
|
|
GroupDescription:
|
|
name: name
|
|
description: Group's description.
|
|
in: query
|
|
schema:
|
|
type: string
|
|
required: false
|
|
example: "group description"
|
|
|
|
GroupID:
|
|
name: groupID
|
|
description: Unique group 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
|
|
|
|
ChannelID:
|
|
name: channelID
|
|
description: Unique group 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
|
|
|
|
MemberID:
|
|
name: memberID
|
|
description: Unique member 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
|
|
|
|
ParentID:
|
|
name: parentID
|
|
description: Unique parent identifier for a group.
|
|
in: query
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
required: false
|
|
example: bb7edb32-2eac-4aad-aebe-ed96fe073879
|
|
|
|
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
|
|
|
|
Tree:
|
|
name: tree
|
|
description: Specify type of response, JSON array or tree.
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
|
|
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
|
|
minimum: 0
|
|
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"
|
|
|
|
requestBodies:
|
|
UserCreateReq:
|
|
description: JSON-formatted document describing the new user to be registered
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UserReqObj"
|
|
|
|
UserUpdateReq:
|
|
description: JSON-formated document describing the metadata and name of user to be update
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UserUpdate"
|
|
|
|
UserUpdateTagsReq:
|
|
description: JSON-formated document describing the tags of user to be update
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UserTags"
|
|
|
|
UserUpdateIdentityReq:
|
|
description: Identity change data. User can change its identity.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UserIdentity"
|
|
|
|
UserUpdateSecretReq:
|
|
description: Secret change data. User can change its secret.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UserSecret"
|
|
|
|
UserUpdateRoleReq:
|
|
description: JSON-formated document describing the role of the user to be updated
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UserRole"
|
|
|
|
GroupCreateReq:
|
|
description: JSON-formatted document describing the new group to be registered
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GroupReqObj"
|
|
|
|
GroupUpdateReq:
|
|
description: JSON-formated document describing the metadata and name of group to be update
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GroupUpdate"
|
|
|
|
AssignReq:
|
|
description: JSON-formated document describing the policy related to assigning members to a group
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AssignReqObj"
|
|
|
|
AssignUserReq:
|
|
description: JSON-formated document describing the policy related to assigning users to a group
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AssignUserReqObj"
|
|
|
|
IssueTokenReq:
|
|
description: Login credentials.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/IssueToken"
|
|
|
|
RequestPasswordReset:
|
|
description: Initiate password request procedure.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
email:
|
|
type: string
|
|
format: email
|
|
description: User email.
|
|
|
|
PasswordReset:
|
|
description: Password reset request data, new password and token that is appended on password reset link received in email.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
password:
|
|
type: string
|
|
format: password
|
|
description: New password.
|
|
minimum: 8
|
|
confirm_password:
|
|
type: string
|
|
format: password
|
|
description: New confirmation password.
|
|
minimum: 8
|
|
token:
|
|
type: string
|
|
format: jwt
|
|
description: Reset token generated and sent in email.
|
|
|
|
PasswordChange:
|
|
description: Password change data. User can change its password.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
password:
|
|
type: string
|
|
format: password
|
|
minimum: 8
|
|
description: New password.
|
|
old_password:
|
|
type: string
|
|
minimum: 8
|
|
format: password
|
|
description: Old password.
|
|
|
|
responses:
|
|
UserCreateRes:
|
|
description: Registered new user.
|
|
headers:
|
|
Location:
|
|
schema:
|
|
type: string
|
|
format: url
|
|
description: Registered user relative URL in the format `/users/<user_id>`
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/User"
|
|
links:
|
|
get:
|
|
operationId: getUser
|
|
parameters:
|
|
userID: $response.body#/id
|
|
get_groups:
|
|
operationId: listUsersInGroup
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
get_channels:
|
|
operationId: listUsersInChannel
|
|
parameters:
|
|
channelID: $response.body#/id
|
|
update:
|
|
operationId: updateUser
|
|
parameters:
|
|
userID: $response.body#/id
|
|
update_tags:
|
|
operationId: updateUserTags
|
|
parameters:
|
|
userID: $response.body#/id
|
|
update_identity:
|
|
operationId: updateUserIdentity
|
|
parameters:
|
|
userID: $response.body#/id
|
|
update_role:
|
|
operationId: updateUserRole
|
|
parameters:
|
|
userID: $response.body#/id
|
|
disable:
|
|
operationId: disableUser
|
|
parameters:
|
|
userID: $response.body#/id
|
|
enable:
|
|
operationId: enableUser
|
|
parameters:
|
|
userID: $response.body#/id
|
|
|
|
UserRes:
|
|
description: Data retrieved.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/User"
|
|
links:
|
|
get_groups:
|
|
operationId: listUsersInGroup
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
get_channels:
|
|
operationId: listUsersInChannel
|
|
parameters:
|
|
channelID: $response.body#/id
|
|
|
|
UserPageRes:
|
|
description: Data retrieved.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UsersPage"
|
|
|
|
GroupCreateRes:
|
|
description: Registered new group.
|
|
headers:
|
|
Location:
|
|
schema:
|
|
type: string
|
|
format: url
|
|
description: Registered group relative URL in the format `/groups/<group_id>`
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Group"
|
|
links:
|
|
get:
|
|
operationId: getGroup
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
get_children:
|
|
operationId: listChildren
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
get_parent:
|
|
operationId: listParents
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
get_channels:
|
|
operationId: listGroupsInChannel
|
|
parameters:
|
|
memberID: $response.body#/id
|
|
get_users:
|
|
operationId: listGroupsByUser
|
|
parameters:
|
|
memberID: $response.body#/id
|
|
update:
|
|
operationId: updateGroup
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
disable:
|
|
operationId: disableGroup
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
enable:
|
|
operationId: enableGroup
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
assign:
|
|
operationId: assignUser
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
unassign:
|
|
operationId: unassignUser
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
|
|
GroupRes:
|
|
description: Data retrieved.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Group"
|
|
links:
|
|
get_children:
|
|
operationId: listChildren
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
get_parent:
|
|
operationId: listParents
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
get_channels:
|
|
operationId: listGroupsInChannel
|
|
parameters:
|
|
memberID: $response.body#/id
|
|
get_users:
|
|
operationId: listGroupsByUser
|
|
parameters:
|
|
memberID: $response.body#/id
|
|
assign:
|
|
operationId: assignUser
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
unassign:
|
|
operationId: unassignUser
|
|
parameters:
|
|
groupID: $response.body#/id
|
|
|
|
GroupPageRes:
|
|
description: Data retrieved.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GroupsPage"
|
|
|
|
MembersPageRes:
|
|
description: Group members retrieved.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/MembersPage"
|
|
|
|
TokenRes:
|
|
description: JSON-formated document describing the user access token used for authenticating into the syetem and refresh token used for generating another access token
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
access_token:
|
|
type: string
|
|
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NjU3OTMwNjksImlhdCI6MTY2NTc1NzA2OSwiaXNzIjoibWFpbmZsdXguYXV0aCIsInN1YiI6ImFkbWluQGV4YW1wbGUuY29tIiwiaXNzdWVyX2lkIjoiZmRjZWVhNWYtNjYxNy00MjY1LWJhZDUtMzYxOTNhOTQ0NjMwIiwidHlwZSI6MH0.3gNd_x01QEiZfQxuQoEyqCqTrcxRkXHO7A4iG_gzu3c
|
|
description: User access token.
|
|
refresh_token:
|
|
type: string
|
|
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NjU3OTMwNjksImlhdCI6MTY2NTc1NzA2OSwiaXNzIjoibWFpbmZsdXguYXV0aCIsInN1YiI6ImFkbWluQGV4YW1wbGUuY29tIiwiaXNzdWVyX2lkIjoiZmRjZWVhNWYtNjYxNy00MjY1LWJhZDUtMzYxOTNhOTQ0NjMwIiwidHlwZSI6MH0.3gNd_x01QEiZfQxuQoEyqCqTrcxRkXHO7A4iG_gzu3c
|
|
description: User refresh token.
|
|
access_type:
|
|
type: string
|
|
example: access
|
|
description: User access token type.
|
|
|
|
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: |
|
|
* User access: "Authorization: Bearer <user_access_token>"
|
|
|
|
refreshAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: |
|
|
* User refresh token used to get another access token: "Authorization: Bearer <user_refresh_token>"
|
|
security:
|
|
- bearerAuth: []
|
|
- refreshAuth: []
|