swagger: '2.0' info: version: 2.1.0 title: Cybus Auth API basePath: /api schemes: - https produces: - application/json consumes: - application/json paths: /api/auth/ldap: get: security: - ApiKeyHeader: [] tags: - ldap summary: LDAP configuration operationId: getLdapConfiguration responses: '200': description: LDAP configuration schema: $ref: '#/definitions/LdapRequest' /api/users: post: security: - ApiKeyHeader: [] tags: - users summary: Create a new user operationId: createUser parameters: - in: body name: body description: User to be created required: true schema: $ref: '#/definitions/UserPostRequest' responses: '201': description: Created schema: $ref: '#/definitions/User' '400': description: Invalid request get: description: Deprecated - instead use GET /listUsers security: - ApiKeyHeader: [] tags: - users summary: List users operationId: listUsers parameters: - in: query name: username[eq] description: Filter by equal to username type: string responses: '200': description: Array of users schema: type: array items: $ref: '#/definitions/User' /api/listUsers: get: security: - ApiKeyHeader: [] tags: - users summary: List users operationId: listUsers parameters: - in: query name: username[eq] description: The optional list to be matched against the usernames schema: oneOf: - type: array items: type: string - type: string - in: query name: pageNumber description: The page number to fetch, starts at page 1 type: integer - in: query name: rowsPerPage description: The number of records per page to return type: integer maximum: 100 - in: query name: excludeAutoGenerated description: If the auto generated roles should be excluded from the results type: boolean responses: '200': description: Object with array of users and pagination information schema: $ref: '#/definitions/PaginatedUsers' '400': description: Bad Request schema: type: object properties: code: type: string description: The error code message: type: string description: A description of the error /api/users/usernames: get: security: - ApiKeyHeader: [] tags: - users summary: List all usernames operationId: listUsernames responses: '200': description: Array of user ids schema: type: array items: $ref: '#/definitions/UserIndex' /api/users/ids: get: security: - ApiKeyHeader: [] tags: - users summary: List user ids operationId: listUserIds responses: '200': description: Array of user ids schema: type: array items: type: string /api/users/batch: post: security: - ApiKeyHeader: [] tags: - users summary: Create new users in batch operationId: createUsersBatch parameters: - in: body name: body description: User to be created required: true schema: type: array items: $ref: '#/definitions/UserPostRequest' responses: '201': description: Created schema: $ref: '#/definitions/NewUserIds' '400': description: Invalid request /api/users/batch/delete: post: security: - ApiKeyHeader: [] tags: - users summary: Delete users in batch operationId: deleteUsersBatch parameters: - in: body name: body description: User IDs to be deleted required: true schema: type: array items: type: string responses: '200': description: ok '400': description: Invalid request /api/users/change-password: put: security: - ApiKeyHeader: [] tags: - users summary: Change user password operationId: changeUserPassword parameters: - in: body name: body description: Credentials required: true schema: $ref: '#/definitions/UserChangePasswordRequest' responses: '204': description: Changed '400': description: Invalid request /api/users/{id}: get: security: - ApiKeyHeader: [] tags: - users summary: Get a specific user operationId: user parameters: - name: id in: path description: Id of user type: string required: true responses: '200': description: User schema: $ref: '#/definitions/User' '404': description: User not found put: security: - ApiKeyHeader: [] tags: - users summary: Update an existing user operationId: updateUser parameters: - in: path description: Id of user name: id required: true type: string - in: body name: body description: Data required for update of a user required: true schema: $ref: '#/definitions/UserPutRequest' responses: '200': description: OK schema: $ref: '#/definitions/User' '400': description: Invalid request '404': description: User not found delete: security: - ApiKeyHeader: [] tags: - users summary: Delete an existing user operationId: deleteUser parameters: - name: id in: path description: Id of user type: string required: true responses: '200': description: OK '404': description: User not found '409': description: Invalid argument error /api/users/{id}/tokens: get: security: - ApiKeyHeader: [] tags: - tokens summary: Get all tokens generated by this user operationId: getUserTokens parameters: - name: id in: path description: Id of user type: string required: true responses: '200': description: List of user generated tokens schema: type: array items: $ref: '#/definitions/Token' '404': description: User not found delete: security: - ApiKeyHeader: [] tags: - tokens summary: Delete all tokens generated by this user operationId: deleteUserTokens parameters: - name: id in: path description: Id of user type: string required: true - name: tokenId in: query description: >- Id of the Token to be deleted. All tokens for the user are deleted if not present. type: string responses: '200': description: Token(s) deleted '404': description: Error ocurred when attempting to delete token(s) /api/users/{id}/certificates: post: security: - ApiKeyHeader: [] tags: - user certificates summary: Add a new certificate to a user operationId: createCertificate parameters: - in: path type: string name: id required: true description: Id of user - in: body name: body description: Certificate to be created required: true schema: $ref: '#/definitions/CertificatePostRequest' responses: '201': description: Created '400': description: Invalid request delete: security: - ApiKeyHeader: [] tags: - user certificates summary: Delete an existing certificate operationId: deleteCertificate parameters: - name: id in: path description: Id of user type: string required: true - in: body name: body description: Data required for deleting a certificate required: true schema: $ref: '#/definitions/CertificateDeleteRequest' responses: '200': description: OK '400': description: Invalid request '404': description: Certificate not found /api/users/{id}/roles: post: security: - ApiKeyHeader: [] tags: - user roles summary: Add a new role to a user operationId: usercreateRole parameters: - in: path type: string name: id required: true description: Id of user - in: body name: body description: Role to be added required: true schema: $ref: '#/definitions/UserRolePostRequest' responses: '201': description: Created '400': description: Invalid request '404': description: User or role not found delete: security: - ApiKeyHeader: [] tags: - user roles summary: Remove a role from a user operationId: deleteUserRole parameters: - name: id in: path description: Id of user type: string required: true - in: body name: body description: Data required for deleting a role required: true schema: $ref: '#/definitions/UserRoleDeleteRequest' responses: '200': description: OK '400': description: Invalid request '404': description: User or role not found '409': description: Invalid argument error /api/roles: post: security: - ApiKeyHeader: [] tags: - roles summary: Create a new role operationId: createRole parameters: - in: body name: body description: Role to be created required: true schema: $ref: '#/definitions/RolePostRequest' responses: '201': description: Created schema: $ref: '#/definitions/Role' '400': description: Invalid request get: security: - ApiKeyHeader: [] tags: - roles summary: List roles operationId: listRoles parameters: - in: query name: name[eq] description: Filter by equal to name type: string responses: '200': description: Array of roles schema: type: array items: $ref: '#/definitions/Role' '401': description: Authentication Error '403': description: Authorization Error /api/roles/page: get: security: - ApiKeyHeader: [] tags: - roles summary: List paginated roles operationId: listPaginatesRoles parameters: - in: query name: names description: Filter by the given names schema: oneOf: - type: array items: type: string - type: string - in: query name: rowsPerPage description: Set the page size of the yielded page type: integer required: true minimum: 1 maximum: 50 - in: query name: pageNumber description: Set the current page to be retrieved type: integer required: true minimum: 1 - in: query name: autoGenerated description: Filter by roles that are or not auto generated, defaults to any type: boolean required: false - in: query name: isShared description: Filter by roles that are or not shared, defaults to any type: boolean required: false responses: '200': description: Object with array of roles and pagination information schema: type: object properties: roles: type: array items: $ref: '#/definitions/PaginatedRole' pagination: $ref: '#/definitions/Pagination' '400': description: Invalid args provided '401': description: Authentication Error '403': description: Authorization Error /api/roles/names: get: security: - ApiKeyHeader: [] tags: - roles summary: List roles operationId: listRoles responses: '200': description: Object with array of roles names and ids schema: type: array items: $ref: '#/definitions/RoleIndex' '401': description: Authentication Error '403': description: Authorization Error /api/roles/{id}: get: security: - ApiKeyHeader: [] tags: - roles summary: Get a specific role operationId: role parameters: - name: id in: path description: Id of role type: string required: true responses: '200': description: Role schema: $ref: '#/definitions/Role' '401': description: Authentication Error '403': description: Authorization Error '404': description: Role not found put: security: - ApiKeyHeader: [] tags: - roles summary: Update an existing role operationId: updateRole parameters: - in: path description: Id of role name: id required: true type: string - in: body name: body description: Data required for update of a role required: true schema: $ref: '#/definitions/RolePutRequest' responses: '200': description: OK schema: $ref: '#/definitions/Role' '400': description: Invalid request '404': description: Role not found delete: security: - ApiKeyHeader: [] tags: - roles summary: Delete an existing role operationId: deleteRole parameters: - name: id in: path description: Id of role type: string required: true responses: '200': description: OK '400': description: Invalid request '404': description: Role not found '409': description: Invalid argument error /api/roles/{id}/permissions: get: security: - ApiKeyHeader: [] tags: - role permissions summary: List permissions operationId: listPermissions parameters: - in: path type: string name: id required: true description: Id of role responses: '200': description: Array of permissions schema: type: array items: $ref: '#/definitions/Permission' '401': description: Authentication Error '403': description: Authorization Error '404': description: Role not found post: security: - ApiKeyHeader: [] tags: - role permissions summary: Add a new permission to a role operationId: createPermission parameters: - in: path type: string name: id required: true description: Id of role - in: body name: body description: Permission to be created required: true schema: $ref: '#/definitions/PermissionPostRequest' responses: '201': description: Created '400': description: Invalid request '409': description: Conflict - permission already declared /api/roles/{id}/permissions/{pemId}: get: security: - ApiKeyHeader: [] tags: - role permissions summary: Update an existing permission operationId: getPermission parameters: - in: path description: Id of role name: id required: true type: string - in: path description: Id of permission name: pemId required: true type: string responses: '200': description: Permission schema: $ref: '#/definitions/Permission' '400': description: Invalid request '404': description: User not found put: security: - ApiKeyHeader: [] tags: - role permissions summary: Update an existing permission operationId: updatePermission parameters: - in: path description: Id of role name: id required: true type: string - in: path description: Id of permission name: pemId required: true type: string - in: body name: body description: Data required for update of a permission required: true schema: $ref: '#/definitions/PermissionPutRequest' responses: '200': description: OK '400': description: Invalid request '404': description: Permission not found delete: security: - ApiKeyHeader: [] tags: - role permissions summary: Delete an existing permission operationId: deletePermission parameters: - name: id in: path description: Id of role type: string required: true - in: path description: Id of permission name: pemId required: true type: string responses: '200': description: OK '400': description: Invalid request '404': description: Permission not found /api/login: post: tags: - session summary: Login into the cybus connectware operationId: login parameters: - in: body name: body description: Authentication credentials required: true schema: $ref: '#/definitions/LoginRequest' responses: '200': description: OK schema: $ref: '#/definitions/LoginResponse' '400': description: Invalid request '403': description: Authentication Error /api/session: get: tags: - session summary: Return the session of the current user operationId: getCurrentUserAuthentication parameters: [] responses: '200': description: OK schema: $ref: '#/definitions/SessionResponse' '401': description: Unauthorized security: - ApiKeyHeader: [] /api/permissions: get: security: - ApiKeyHeader: [] tags: - permissions summary: Return the permissions of the current user operationId: getCurrentUserPermissions responses: '200': description: OK '401': description: Unauthorized /api/permissions/page: get: security: - ApiKeyHeader: [] tags: - permissions summary: Return a page of all permissions operationId: getPermissionsPage parameters: - in: query name: ids description: Filter by the given permission ids schema: oneOf: - type: array items: type: string - type: string - in: query name: rowsPerPage description: Set the page size of the yielded page type: integer required: true minimum: 1 maximum: 50 - in: query name: pageNumber description: Set the current page to be retrieved type: integer required: true minimum: 1 responses: '200': description: Object with array of permissions and pagination information schema: type: object properties: permissions: type: array items: $ref: '#/definitions/PermissionWithUsage' pagination: $ref: '#/definitions/Pagination' '400': description: Invalid args provided '401': description: Unauthorized /api/permissions/ids: get: security: - ApiKeyHeader: [] tags: - permissions summary: Return a page of all permissions operationId: getPermissionsPage responses: '200': description: >- The ids of all permissions aggregated by resource, operation and context schema: type: array items: $ref: '#/definitions/PermissionIndex' '401': description: Unauthorized /api/logout: post: tags: - session summary: Logout of the cybus connectware operationId: logout parameters: - in: body name: body description: Token data required: true schema: $ref: '#/definitions/LogoutRequest' responses: '200': description: OK '400': description: Invalid request '404': description: Token not found /api/client-registry/register: post: tags: - registration summary: Endpoint for self-registration of clients operationId: requestAccess parameters: - in: body name: body required: true schema: $ref: '#/definitions/ClientRegistryRequest' responses: '201': description: >- Granted. The registration request has been confirmed, proceed to login schema: $ref: '#/definitions/ClientRegistryPositiveResponse' '202': description: >- Pending. The registration request has been accepted but needs to be confirmed. Try again later. '400': description: Invalid Request. '409': description: >- Conflict. Might indicate that a conflicting registration is pending or a conflicting user is already existing. '422': description: >- Policy violation. A user name or a password doesn't fulfill some of the policy rules. schema: $ref: '#/definitions/ClientRegistryPolicyViolationResponse' '423': description: >- Locked. The registration endpoint is currently not open. Try again later. /api/client-registry: get: security: - ApiKeyHeader: [] tags: - registration summary: Receive a list of all pending registration requests operationId: getPendingRequests responses: '200': description: OK schema: $ref: '#/definitions/AuthRequestsResponse' '401': description: Unauthorized /api/client-registry/status: get: security: - ApiKeyHeader: [] tags: - registration summary: Return the current lock status of the registration endpoint operationId: getRegistrationEndpointStatus responses: '200': description: OK schema: $ref: '#/definitions/RegistrationEndpointStatusResponse' /api/client-registry/open: post: security: - ApiKeyHeader: [] tags: - registration summary: Open the registration endpoint temporarily operationId: openRegistrationEndpoint parameters: - in: body name: body required: true schema: $ref: '#/definitions/OpenRegistrationEndpointRequest' responses: '204': description: OK '401': description: Unauthorized /api/client-registry/lock: post: security: - ApiKeyHeader: [] tags: - registration summary: >- Lock the registration endpoint now. This will flush the internal request cache. operationId: lockRegistrationEndpoint responses: '204': description: OK '401': description: Unauthorized /api/client-registry/confirm: post: security: - ApiKeyHeader: [] tags: - registration summary: Confirm a single authentication request operationId: confirmRequest parameters: - in: body name: body required: true schema: $ref: '#/definitions/ConfirmRegistrationRequest' responses: '204': description: OK schema: $ref: '#/definitions/User' '401': description: Unauthorized '404': description: Corresponding username not found /api/certificates: get: security: - ApiKeyHeader: [] tags: - certificates summary: List certificates operationId: listCertificates responses: '200': description: Array of certficates schema: type: array items: $ref: '#/definitions/CybusCertificate' '500': description: Error reading certificates delete: security: - ApiKeyHeader: [] tags: - certificates summary: Deletes certificate operationId: deleteCertificate parameters: - name: id in: query description: Id of certificate type: string required: true responses: '200': description: OK '400': description: Invalid request '404': description: Certificate not found '500': description: Error while attempting to delete Certificate post: security: - ApiKeyHeader: [] tags: - certificates summary: Add certificate operationId: addCertificate parameters: - in: body name: body description: >- Certificate content to be added, a chain can be passed and will be accepted required: true schema: type: string responses: '201': description: Array of added certficates schema: type: array items: $ref: '#/definitions/CybusCertificate' '400': description: Invalid request /api/certificates/content: get: security: - ApiKeyHeader: [] tags: - certificates summary: Returns given certificate content operationId: loadCertificateContent parameters: - name: id in: query description: Id of certificate type: string required: true responses: '200': description: Certificate content schema: type: string '400': description: Invalid request '404': description: Certificate not found '500': description: Error while attempting to delete Certificate /api/broker/auth/enhanced: post: tags: - vernemq summary: Enhanced authentication of MQTT5 (not supported) operationId: enhanced parameters: - in: body name: body description: Not supported required: true schema: $ref: '#/definitions/MQTTEnhancedRequest' responses: '200': description: OK schema: $ref: '#/definitions/MQTTResponse' /api/policy/password: get: security: - ApiKeyHeader: [] tags: - password policy summary: Return a password policy rules operationId: policyPassword responses: '200': description: OK schema: $ref: '#/definitions/PasswordPolicy' /api/maintenance/db: get: security: - ApiKeyHeader: [] tags: - database maintenance summary: Return a database maintenance status operationId: maintenanceDb responses: '200': description: OK schema: $ref: '#/definitions/MaintenanceDb' /api/maintenance/db/backup: get: security: - ApiKeyHeader: [] tags: - database backup download summary: Download a database backup operationId: maintenanceDbBackupDownload responses: '200': description: OK content: application/gzip: schema: type: string '423': description: >- Locked. There is a database maintenance operation in the process. Try again later. post: security: - ApiKeyHeader: [] tags: - database backup start summary: Start a database backup operationId: maintenanceDbBackupStart requestBody: content: multipart/form-data: schema: type: string format: binary responses: '202': description: Accepted. Database backup started. '423': description: >- Locked. There is a database maintenance operation in the process. Try again later. /api/maintenance/db/restore: post: security: - ApiKeyHeader: [] tags: - database upload archive and restore start summary: Upload archive and start database restore operationId: maintenanceDbUploadRestore responses: '202': description: >- Accepted. The archive is uploaded, and the database restores process starts. '423': description: >- Locked. There is a database maintenance operation in the process. Try again later. /api/mfa/enable: post: security: - ApiKeyHeader: [] tags: - mfa summary: Enable MFA for an existing user operationId: enableMfa responses: '200': description: ok schema: $ref: '#/definitions/MfaEnableResponse' '400': description: Invalid request '409': description: User is already enrolled '500': description: Internal error /api/mfa/validate: post: security: - ApiKeyHeader: [] tags: - mfa summary: Validate MFA enrollment of the user operationId: validateEnrollment parameters: - in: body name: body description: User to validate required: true schema: $ref: '#/definitions/MfaValidatePostRequest' responses: '200': description: ok schema: $ref: '#/definitions/MfaValidateResponse' '400': description: Invalid request '401': description: Invalid OTP '500': description: Internal error /api/mfa/login: post: security: - ApiKeyHeader: [] tags: - mfa summary: Login user with MFA operationId: loginMfa parameters: - in: body name: body description: All necessary data for logging in with MFA required: true schema: $ref: '#/definitions/MfaLoginPostRequest' responses: '200': description: ok schema: $ref: '#/definitions/LoginResponse' '400': description: Invalid request '401': description: Invalid OTP '500': description: Internal error /api/mfa/disable: post: security: - ApiKeyHeader: [] tags: - mfa summary: User self de-registration from MFA operationId: disableMfa parameters: - in: body name: body description: User to disable required: true schema: $ref: '#/definitions/MfaDisablePostRequest' responses: '200': description: ok '400': description: Invalid request '500': description: Internal error /api/mfa/regenerate/backupcodes: post: security: - ApiKeyHeader: [] tags: - mfa summary: Regenarete backup codes a user operationId: regenerateBackupcodes parameters: - in: body name: body description: User to regenerate codes for required: true schema: $ref: '#/definitions/MfaRegeneratePostRequest' responses: '200': description: ok schema: $ref: '#/definitions/RegenerateResponse' '400': description: Invalid request '500': description: Internal error /api/mfa/isenrolled: get: security: - ApiKeyHeader: [] tags: - mfa summary: Checks if a user is enrolled to mfa or not operationId: isenrolled responses: '200': description: ok schema: $ref: '#/definitions/IsEnrolledResponse' '400': description: Invalid request '500': description: Internal error securityDefinitions: ApiKeyHeader: type: apiKey in: header name: Authorization definitions: LdapRequest: type: object required: - enabled properties: enabled: type: boolean default: false mode: type: string default: GROUP UserPostRequest: type: object required: - username - identityProvider - grantTypes properties: username: type: string minLength: 3 autoGenerated: type: boolean default: false mqttPublishPrefix: type: string password: type: string minLength: 5 identityProvider: $ref: '#/definitions/IdentityProvider' grantTypes: type: array items: $ref: '#/definitions/GrantType' certificates: type: array items: $ref: '#/definitions/Certificate' initialPermissions: type: array items: $ref: '#/definitions/Permission' roles: type: array description: >- An array of roleId of the roles the new user should have. (Must be roleId, not role name.) items: type: string enforceMFAEnrollment: type: boolean default: false UserPutRequest: type: object properties: username: type: string minLength: 3 password: type: string mqttPublishPrefix: type: string identityProvider: $ref: '#/definitions/IdentityProvider' grantTypes: type: array items: $ref: '#/definitions/GrantType' roles: type: array description: >- An array of roleId of the roles the new user should have. (Must be roleId, not role name.) items: type: string permissions: type: array items: $ref: '#/definitions/Permission' disableMfa: type: boolean description: Indicates that MFA for the given user should be disabled enforceMFAEnrollment: type: boolean description: Enforces the user to enroll MFA UserChangePasswordRequest: type: object properties: password: type: string newPassword: type: string minLength: 5 CertificatePostRequest: type: object required: - fingerprint properties: fingerprint: type: string CertificateDeleteRequest: type: object required: - fingerprint properties: fingerprint: type: string UserRolePostRequest: type: object required: - roleId properties: roleId: type: string UserRoleDeleteRequest: type: object required: - roleId properties: roleId: type: string RolePostRequest: type: object required: - name - isShared properties: name: type: string isShared: type: boolean autoGenerated: type: boolean permissions: type: array items: $ref: '#/definitions/Permission' RolePutRequest: type: object required: - name properties: name: type: string isShared: type: boolean permissions: type: array items: $ref: '#/definitions/Permission' PermissionPostRequest: type: object required: - resource - operation - context properties: resource: type: string operation: $ref: '#/definitions/Operation' context: $ref: '#/definitions/Context' PermissionPutRequest: type: object required: - operation properties: resource: type: string operation: $ref: '#/definitions/Operation' AuthenticatePostRequest: type: object properties: userName: type: string userId: type: string token: type: string certificate: type: string password: type: string AuthenticateResponse: type: object required: - isAuthenticated - userId properties: isAuthenticated: type: boolean userId: type: string AuthorizePostRequest: type: object required: - userId - resource - operation - context properties: userName: type: string userId: type: string resource: type: string operation: $ref: '#/definitions/Operation' context: $ref: '#/definitions/Context' AuthorizedResponse: type: object required: - isAuthorized properties: isAuthorized: type: boolean LoginRequest: type: object required: - username - password properties: username: type: string password: type: string expireTimeInHours: type: number label: type: string LoginResponse: type: object properties: token: type: string expiresAt: type: string permissions: type: array description: Permissions the authenticated user has items: $ref: '#/definitions/Permission' needsMfa: type: boolean description: Present when MFA was enrolled by the user already secret: type: string enforceMFAEnrollment: type: boolean description: Present when MFA has to be enrolled but was not enrolled by the user SessionResponse: type: object properties: username: type: string expiresAt: type: string permissions: type: array description: Permissions the authenticated user has items: $ref: '#/definitions/Permission' LogoutRequest: type: object required: - token properties: token: type: string MQTTRegisterRequest: type: object properties: peer_addr: type: string peer_port: type: integer mountpoint: type: string client_id: type: string clean_session: type: boolean MQTTPublishRequest: type: object properties: username: type: string client_id: type: string mountpoint: type: string qos: type: integer topic: type: string payload: type: string retain: type: boolean MQTTSubscribeRequest: type: object properties: mountpoint: type: string username: type: string topics: type: array items: type: object properties: topic: type: string qos: type: integer MQTTEnhancedRequest: type: object properties: client_id: type: string properties: type: object properties: p_authentication_method: type: string OpenRegistrationEndpointRequest: type: object properties: duration: type: integer description: >- This parameter defines how long the registration endpoint will be kept open (in milliseconds). Default if undefined: 30000 milliseconds example: 30000 ConfirmRegistrationRequest: type: object required: - username properties: username: type: string description: >- Username to confirm. Must match a username that is currently in the pendingRequests list. minLength: 3 mqttPublishPrefix: type: string grantTypes: type: array items: $ref: '#/definitions/GrantType' initialPermissions: type: array items: $ref: '#/definitions/Permission' roles: type: array description: >- An array of roleId of the roles the new user should have. (Must be roleId, not role name.) items: type: string ClientRegistryRequest: type: object required: - context - username properties: username: type: string minLength: 3 description: >- Username to be registered. The Auth Server will check this for uniqueness, so be sure to generate a reasonably namespaced username. example: iot.device.0123456 password: type: string minLength: 5 description: >- Secret password that should be set for the user. This will be stored in hashed form on the receiver side. Either this or a csr should be supplied. example: secret-password csr: type: string description: >- Base 64 encoded certificate signing request in PEM format. Instead of a password, a client side certificate (x.509) can be used for authentication. If the CSR is supplied, the signed certificate will be returned once the authentication request is granted. example: > LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQ3REQ0NBWndDQVFBd2J6RUxN QWtHQTFVRUJoTUNSRVV4RHpBTkJnTlZCQWdNQmtKbGNteHBiakVVTUJJRwpBMVVFQ2d3TFVtOWli M1J6SUVsdVl5NHhEREFLQmdOVkJBc01BMUltUkRFTk1Bc0dBMVVFQXd3RVVqSkVNakVjCk1Cb0dD U3FHU0liM0RRRUpBUllOY2pKa01rQmplV0oxY3k1cGJ6Q0NBU0l3RFFZSktvWklodmNOQVFFQkJR QUQKZ2dFUEFEQ0NBUW9DZ2dFQkFNSXlsQmk4azFIZDJseERXZHd5N1Z3WngvaUlrdWpTUUVtWmdk Y0JqNk4veTZTSQpiTGMwdFpmK2JGWUZZZ2p0OHRFUUJPRzhNeW94YmYwQSs4T0dHZFJvV3l2eHFt ci9TLzhNa1ZGUXJiS2duMDBaCmVrdWlZQVBUOFMvT0FZVnlGT21rWWtWSm0wdkRwMmRkcXRiTUZY bXZ1OGxnVnVPckFwMEQ4TjdBcVgwWlUwc0UKZzRmVkdpREtnS040cUFEcXR3aVZKb0dsR0JCYWpm ejAxSlhEWnhpUEVac3BYSGJyaVY0Z1JvV0VIVGNGcWc4cgo1WCtZRDlqTGVGdFdRb0g5SHA3ZEFP Y1lCRktVRVZjWTlGN20vRWZkVFBwNjNnbTdRdFR4S0EvelIyODRWQUVCCjZFbC8xU2FCME54YlVw bHgzVHp4T2ZKYjJpdEd0S1RzN1U2UnF3VUNBd0VBQWFBQU1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0 SUJBUUIxejdKcGRIRERScTl2WE1BMmNBVVZBRmYvYkRXNzlkNmlMQ0pDVDZ5WlhOcHV0ZXA3N1pQ dQpIMSszb08vZmRJdDhaOThjV0J4ZVBNckVDM2krQ0lIdms4a202SVFMVW05cUZVdHRDN0VjUmpU UFYwT29vb2l0ClhXOHhzWVhGaEZPTStydTJnbEcrSUVMY3BydS9JamxyVHpwaUtNZVJGQ1FFemww WWtZRDZkSk82ME1CRVhjZUgKWHpFZTRtT2oxUDJKNFcycFI1bDFsQjZ5dXB4SWVuRjRhNm5EeFFE eFZkcmtBTHNJdDhGZUNTNDNvaHg4NVQ5SApHN2IwOFdmdEFrYzhKR3ZLb00rdE90MzlVZFFESE1S OU5QOG9RUUpMaldMcWZRdUtaRmZXNVJyR24zSzA2UGNICkRMN1FNc1hxNFBaMyswUXpCSjZJVGoz aUZubHp1VXBqCi0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo= roles: type: array description: Name of roles the user wants to be assigned to items: type: string example: manufacturer.iotModule.simpleRole permissions: type: array description: Permissions the user wants to be granted individually items: $ref: '#/definitions/Permission' context: type: string description: >- Free text that helps the granting user understanding where this request comes from. example: IoT Device Serial Number <0123456> RegistrationEndpointStatusResponse: type: object required: - status properties: status: type: string enum: - open - locked unlockedUntil: status: type: number MQTTResponse: type: object properties: result: type: string modifiers: type: object properties: max_message_size: type: string max_inflight_messages: type: string retry_interval: type: string EnvoyGetResponse: type: object properties: certificates: type: array items: type: object properties: fingerprint_sha256: type: string AuthRequestsResponse: type: array items: type: object properties: timestamp: type: string description: String with ISO 8601 timestamp of the last request update. example: '2022-03-25T17:25:21.379Z' username: type: string description: Username that is requested to be granted access. example: iot.device.0123456 credentialType: type: string enum: - certificate - password roles: type: array items: type: string context: type: string description: >- Free text that helps the granting user understanding where this request comes from. example: IoT Device Serial Number <0123456> permissions: $ref: '#/definitions/Permission' granted: type: boolean ClientRegistryPositiveResponse: type: object properties: certificate: type: string description: >- Signed certificate in Base64 encoded PEM format. This is only supplied if a CSR had been present in the registration payload. example: > LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVyVENDQXBXZ0F3SUJBZ0lVS0pYWUpZNWdK NExMbHpvSlcvUi9iczMxakw0d0RRWUpLb1pJaHZjTkFRRUYKQlFBd2dZMHhFekFSQmdOVkJBb01D a041WW5WeklFZHRZa2d4RkRBU0JnTlZCQXNNQzBSbGRtVnNiM0J0Wlc1MApNUjB3R3dZSktvWklo dmNOQVFrQkZnNW9aV3hzYjBCamVXSjFjeTVwYnpFUU1BNEdBMVVFQnd3SFNHRnRZblZ5Clp6RVFN QTRHQTFVRUNBd0hTR0Z0WW5WeVp6RUxNQWtHQTFVRUJoTUNSRVV4RURBT0JnTlZCQU1NQjBONVlu VnoKUTBFd0hoY05Nakl3TlRFMk1URXlNVFU1V2hjTk1qTXdOVEUyTVRFeU1UVTVXakJ2TVFzd0NR WURWUVFHRXdKRQpSVEVQTUEwR0ExVUVDQXdHUW1WeWJHbHVNUlF3RWdZRFZRUUtEQXRTYjJKdmRI TWdTVzVqTGpFTU1Bb0dBMVVFCkN3d0RVaVpFTVEwd0N3WURWUVFEREFSU01rUXlNUnd3R2dZSktv WklodmNOQVFrQkZnMXlNbVF5UUdONVluVnoKTG1sdk1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFB T0NBUThBTUlJQkNnS0NBUUVBd2pLVUdMeVRVZDNhWEVOWgozREx0WEJuSCtJaVM2TkpBU1ptQjF3 R1BvMy9McEloc3R6UzFsLzVzVmdWaUNPM3kwUkFFNGJ3ektqRnQvUUQ3Cnc0WVoxR2hiSy9HcWF2 OUwvd3lSVVZDdHNxQ2ZUUmw2UzZKZ0E5UHhMODRCaFhJVTZhUmlSVW1iUzhPbloxMnEKMXN3VmVh Kzd5V0JXNDZzQ25RUHczc0NwZlJsVFN3U0RoOVVhSU1xQW8zaW9BT3EzQ0pVbWdhVVlFRnFOL1BU VQpsY05uR0k4Um15bGNkdXVKWGlCR2hZUWROd1dxRHl2bGY1Z1AyTXQ0VzFaQ2dmMGVudDBBNXhn RVVwUVJWeGowClh1YjhSOTFNK25yZUNidEMxUEVvRC9OSGJ6aFVBUUhvU1gvVkpvSFEzRnRTbVhI ZFBQRTU4bHZhSzBhMHBPenQKVHBHckJRSURBUUFCb3lJd0lEQUpCZ05WSFJNRUFqQUFNQk1HQTFV ZEpRUU1NQW9HQ0NzR0FRVUZCd01DTUEwRwpDU3FHU0liM0RRRUJCUVVBQTRJQ0FRQmpkWGtBaUtJ WUd0Q3RIMDVwck1hbWhZSHl3cFNYdzBPSzB4bTBMcFlTCkpvc094OWFGVjRqcS9Fb3NlWlZndkR0 OGM0ajlXVlBkQ1lmOHlwaHVFRS8yM2s3akEzaFlYZmFIZnVoenZnaWgKSDB3U0Q2WmgrNGptaDdE V0tEVnRwOWI4aFBmdytzR3ltYUtkaWM4WFNVMlNDK1RMNGRYTkFlTjFIeVVtanltcApRZFZBamsx QXNRT3YvU0gzaEg4cmJBWEprMWpoTks0Z2tGT0oxTHJ5TkR3dmNPc3JHbFpLY3BsWStKVE1HZkFH CjUyYmFtdGpIVG9FQ1BSOGhIeGx6bTlFYUxidUtpUlpwZ242M25qYWRWK1d4a09zVTlPSUM3dm9U SlNtQ3VOZmkKdjh1RmdsSUFGS0JXSmVOZERxQk5OZnBjTU5GTDV0R1NIbzkvVEtLQ3hEam1QN3Ns c3BRMzVYTFluODl1MjY3agpJZmU2dkppdXZxdXdyN0c1S1orTTkvQitlWk5ISHVrNEFDTUs5OFk1 cWhtb2pQS3p5Z202b2FiRzI3bk1EYzF5CkM0Q05LUWUrL1J5SEdYbXFjdm5ZVGxHVGpNWktoRWpX OVp3UmJyZVZ1M1lmNVhlZU95OXNpOWs5VTI3bVQ0UTUKdC8zU2xCK2JiTW4vbzVPWFI0YStnT2VX VWVJRzl6SzNvYVdXbmVKVlZPdmRlQy8xTjY0ajRERjlKWm45cGtENgowdUozQUFKMUYvN2tJa2tT MXNmZWdjejZCU2pkMldkQjhHaDZSN1ZVS0VPSEpCREphZm1EdkRjVGdSZytQa1NUCmpjdHVzVnNl Yi9lcE1BRkQ1dERuUDFHVU8yYkx2dzQ3QWl0akxKdnljeUZZbnovU1ZFK2dXOTU3ZEpXcVVjZEkK YXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCgo= ClientRegistryPolicyViolationResponse: type: object required: - code - message properties: code: type: integer description: >- Define on which property is a policy failure. 0 is a username, 1 is a password. minimum: 0 maximum: 1 message: type: string description: A policy failure description. details: type: object description: Provides details of the violated rules. properties: username: type: string description: It contains the username that breaks the rule. min: type: object description: >- It provides details about the minimum password length policy requirement. $ref: '#/definitions/PasswordPolicyViolationDetailsRule' upper: type: object description: >- It provides details about the required number of upper-case letters. $ref: '#/definitions/PasswordPolicyViolationDetailsRule' lower: type: object description: >- It provides details about the required number of lower-case letters. $ref: '#/definitions/PasswordPolicyViolationDetailsRule' numeric: type: object description: >- It provides details about the required number of numeric characters. $ref: '#/definitions/PasswordPolicyViolationDetailsRule' symbol: type: object description: >- It provides details about the required number of symbols/punctuations. $ref: '#/definitions/PasswordPolicyViolationDetailsRule' PasswordPolicyViolationDetailsRule: type: object description: It provides a password policy rule violation details properties: required: type: integer description: A required number for a particular rule (number of chars or length). minimum: 0 current: type: integer description: A current number for a particular rule (number of chars or length). minimum: 0 message: type: string description: A violation message. CybusCertificate: type: object properties: id: type: string issuedBy: type: object properties: commonName: type: string organization: type: string organizationalUnit: type: string issuedTo: type: object properties: commonName: type: string organization: type: string organizationalUnit: type: string alternativeNames: type: array items: type: string keyUsage: type: array items: type: string extendedKeyUsage: type: array items: type: string basicConstraints: type: object properties: isCA: type: boolean pathLength: type: number issuedOn: type: number expiresOn: type: number fingerprints: type: object properties: sha1: type: string sha256: type: string removable: type: boolean User: type: object properties: id: type: string username: type: string autoGenerated: type: boolean mqttPublishPrefix: type: string identityProvider: $ref: '#/definitions/IdentityProvider' grantTypes: type: array items: $ref: '#/definitions/GrantType' tokens: type: array items: $ref: '#/definitions/Token' certificates: type: array items: $ref: '#/definitions/Certificate' roles: type: array items: $ref: '#/definitions/Role' mfa_is_enrolled: type: boolean enforceMFAEnrollment: type: boolean PaginatedUsers: type: object properties: users: type: array items: $ref: '#/definitions/User' pagination: $ref: '#/definitions/Pagination' Pagination: type: object properties: totalPages: type: integer description: Number of pages available totalRows: type: integer description: Total number of rows available totalRowsInPage: type: integer description: Total number of rows for the selected page currentPage: type: integer description: Returned page number nextPage: type: integer description: The next page rowsPerPage: type: integer description: The number of rows per page requested by the client UserIndex: type: object properties: username: type: string id: type: string RoleIndex: type: object properties: id: type: string name: type: string PermissionIndex: type: object properties: resource: type: string description: The permission's resource operation: $ref: '#/definitions/Operation' context: $ref: '#/definitions/Context' ids: description: >- The ids that have the same aformentioned resource, operation and context type: array items: type: string NewUserIds: type: array items: type: string IdentityProvider: type: string enum: - local - ldap GrantType: type: object properties: method: $ref: '#/definitions/Method' isRequired: type: boolean Method: type: string enum: - password - token - certificate Token: type: object properties: fingerprint: type: string createdAt: type: string expiresAt: type: string label: type: string Certificate: type: object properties: fingerprint: type: string createdAt: type: string expiresAt: type: string Role: type: object properties: id: type: string name: type: string isShared: type: boolean permissions: type: array items: $ref: '#/definitions/Permission' PaginatedRole: type: object properties: id: type: string name: type: string isshared: type: boolean autogenerated: type: boolean users: description: >- The array will always have at least one element, will null values if there are no users type: array items: type: object properties: id: schema: oneOf: - type: 'null' - type: string description: The id of the usern username: schema: oneOf: - type: 'null' - type: string description: The username of the user permissions: type: array items: type: object properties: id: schema: oneOf: - type: 'null' - type: string description: Id of the permission resource: schema: oneOf: - type: 'null' - type: string description: Resource of the permission operation: schema: oneOf: - type: 'null' - $ref: '#/definitions/Operation' description: Operation of the permission context: schema: oneOf: - type: 'null' - $ref: '#/definitions/Context' description: Context of the permission Permission: type: object properties: id: type: string resource: type: string description: >- The MQTT topic or REST URL path for which the permission is granted. Both may include MQTT-style wildcards. operation: $ref: '#/definitions/Operation' context: $ref: '#/definitions/Context' PermissionWithUsage: type: object properties: resource: type: string description: The permission's resource context: $ref: '#/definitions/Context' usage: type: array items: type: object properties: roleName: type: string description: Role name of the role that has this permission roleId: type: string description: Role id of the role that has this permission isRoleShared: type: string description: If the role is shared or not username: schema: oneOf: - type: 'null' - type: string description: >- Username of the user that has this permission, if there is only a role userId: schema: oneOf: - type: 'null' - type: string description: The user of the permission operation: $ref: '#/definitions/Operation' Operation: type: string enum: - read - write - readWrite Context: type: string enum: - http - mqtt PasswordPolicy: type: object properties: min: type: integer description: >- The minimum number of characters a password must contain. Zero disables this rule. lower: type: integer description: >- The minimum number of lower-case letters a password must contain. Zero disables this rule. upper: type: integer description: >- The minimum number of upper-case letters a password must contain. Zero disables this rule. numeric: type: integer description: >- The minimum number of digit numbers a password must contain. Zero disables this rule. symbol: type: integer description: >- The minimum number of symbol or punctuation characters a password must contain. Zero disables this rule. MaintenanceDb: type: object properties: running: type: boolean description: Indicate the current running status of a backup/restore operation. backup: $ref: '#/definitions/MaintenanceDbStatus' restore: $ref: '#/definitions/MaintenanceDbStatus' MaintenanceDbStatus: type: object properties: id: type: string description: The backup/restore id succeeded: type: boolean description: Indicate the failure status from the last backup/restore operation. statusMessage: type: string description: Describe the reason for the failure, if any startDate: type: date-time description: Start date and time of a last backup/restore operation. endDate: type: date-time description: End date and time of a last backup/restore operation. MfaEnableResponse: type: object properties: uri: type: string example: >- otpauth://totp/Cybus:Connectware?issuer=Cybus&secret=something&algorithm=SHA1&digits=6&period=30 required: - uri MfaValidatePostRequest: type: object properties: otp: type: string required: - otp MfaValidateResponse: type: object properties: backupCodes: type: array items: type: string required: - backupCodes MfaLoginPostRequest: type: object properties: username: type: string otp: type: string backupCode: type: string secret: type: string required: - username - secret MfaDisablePostRequest: type: object properties: otp: type: string backupCode: type: string MfaRegeneratePostRequest: type: object properties: otp: type: string backupCode: type: string RegenerateResponse: type: object properties: backupCodes: type: array items: type: string required: - backupCodes IsEnrolledResponse: type: object properties: isEnrolled: boolean required: - isEnrolled