Contact Uscybus.io

User Management (API)

86KB
Auth-Server Schema.yaml

LDAP configuration

get
Authorizations
Responses
curl -L \
  --url '/auth/ldap' \
  --header 'Authorization: YOUR_API_KEY'
{
  "enabled": true,
  "mode": "text"
}

LDAP configuration

MFA configuration

get
Authorizations
Responses
curl -L \
  --url '/auth/mfa' \
  --header 'Authorization: YOUR_API_KEY'
{
  "enabled": true
}

MFA configuration

MS Entra ID configuration

get
Responses
curl -L \
  --url '/auth/msEntraId'
{
  "enabled": true
}

MS Entra ID configuration

Create a new user

post
Authorizations
Body
usernamestring · min: 3required
autoGeneratedboolean · default: falseoptional
mqttPublishPrefixstringoptional
passwordstring · min: 5optional
identityProviderstring · enumrequired
Options: local, ldap, msentraid
grantTypesobject[]required

certificatesobject[]optional

initialPermissionsobject[]optional

rolesstring[]optional

An array of roleId of the roles the new user should have. (Must be roleId, not role name.)

enforceMFAEnrollmentboolean · default: falseoptional
Responses
curl -L \
  --request POST \
  --url '/users' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "text",
    "autoGenerated": true,
    "mqttPublishPrefix": "text",
    "password": "text",
    "identityProvider": "local",
    "grantTypes": [
      {
        "method": "password",
        "isRequired": true
      }
    ],
    "certificates": [
      {
        "fingerprint": "text",
        "createdAt": "text",
        "expiresAt": "text"
      }
    ],
    "initialPermissions": [
      {
        "id": "text",
        "resource": "text",
        "operation": "read",
        "context": "http"
      }
    ],
    "roles": [
      "text"
    ],
    "enforceMFAEnrollment": true
  }'
{
  "id": "text",
  "username": "text",
  "autoGenerated": true,
  "mqttPublishPrefix": "text",
  "identityProvider": "local",
  "grantTypes": [
    {
      "method": "password",
      "isRequired": true
    }
  ],
  "tokens": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text",
      "label": "text"
    }
  ],
  "certificates": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text"
    }
  ],
  "roles": [
    {
      "id": "text",
      "name": "text",
      "isShared": true,
      "permissions": [
        {
          "id": "text",
          "resource": "text",
          "operation": "read",
          "context": "http"
        }
      ],
      "ldapGroupDn": "text",
      "msEntraIdGroupId": "text"
    }
  ],
  "mfa_is_enrolled": true,
  "enforceMFAEnrollment": true
}

Created

List users

get
Authorizations
Query parameters
username[eq]anyoptional

The optional list to be matched against the usernames

pageNumberanyoptional

The page number to fetch, starts at page 1

rowsPerPageanyoptional

The number of records per page to return

excludeAutoGeneratedanyoptional

If the auto generated roles should be excluded from the results

Responses
curl -L \
  --url '/listUsers' \
  --header 'Authorization: YOUR_API_KEY'
{
  "users": [
    {
      "id": "text",
      "username": "text",
      "autoGenerated": true,
      "mqttPublishPrefix": "text",
      "identityProvider": "local",
      "grantTypes": [
        {
          "method": "password",
          "isRequired": true
        }
      ],
      "tokens": [
        {
          "fingerprint": "text",
          "createdAt": "text",
          "expiresAt": "text",
          "label": "text"
        }
      ],
      "certificates": [
        {
          "fingerprint": "text",
          "createdAt": "text",
          "expiresAt": "text"
        }
      ],
      "roles": [
        {
          "id": "text",
          "name": "text",
          "isShared": true,
          "permissions": [
            {
              "id": "text",
              "resource": "text",
              "operation": "read",
              "context": "http"
            }
          ],
          "ldapGroupDn": "text",
          "msEntraIdGroupId": "text"
        }
      ],
      "mfa_is_enrolled": true,
      "enforceMFAEnrollment": true
    }
  ],
  "pagination": {
    "totalPages": 1,
    "totalRows": 1,
    "totalRowsInPage": 1,
    "currentPage": 1,
    "nextPage": 1,
    "rowsPerPage": 1
  }
}

Object with array of users and pagination information

List all usernames

get
Authorizations
Responses
curl -L \
  --url '/users/usernames' \
  --header 'Authorization: YOUR_API_KEY'
[
  {
    "username": "text",
    "id": "text"
  }
]

Array of user ids

List user ids

get
Authorizations
Responses
curl -L \
  --url '/users/ids' \
  --header 'Authorization: YOUR_API_KEY'
[
  "text"
]

Array of user ids

Create new users in batch

post
Authorizations
Body
usernamestring · min: 3required
autoGeneratedboolean · default: falseoptional
mqttPublishPrefixstringoptional
passwordstring · min: 5optional
identityProviderstring · enumrequired
Options: local, ldap, msentraid
grantTypesobject[]required

certificatesobject[]optional

initialPermissionsobject[]optional

rolesstring[]optional

An array of roleId of the roles the new user should have. (Must be roleId, not role name.)

enforceMFAEnrollmentboolean · default: falseoptional
Responses
curl -L \
  --request POST \
  --url '/users/batch' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "username": "text",
      "autoGenerated": true,
      "mqttPublishPrefix": "text",
      "password": "text",
      "identityProvider": "local",
      "grantTypes": [
        {
          "method": "password",
          "isRequired": true
        }
      ],
      "certificates": [
        {
          "fingerprint": "text",
          "createdAt": "text",
          "expiresAt": "text"
        }
      ],
      "initialPermissions": [
        {
          "id": "text",
          "resource": "text",
          "operation": "read",
          "context": "http"
        }
      ],
      "roles": [
        "text"
      ],
      "enforceMFAEnrollment": true
    }
  ]'
[
  "text"
]

Created

Delete users in batch

post
Authorizations
Body
string[]optional
Responses
curl -L \
  --request POST \
  --url '/users/batch/delete' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '[
    "text"
  ]'
No body

ok

Change user password

put
Authorizations
Body
passwordstringoptional
newPasswordstring · min: 5optional
Responses
curl -L \
  --request PUT \
  --url '/users/change-password' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "password": "text",
    "newPassword": "text"
  }'
No body

Changed

Get a specific user

get
Authorizations
Path parameters
idanyrequired

Id of user

Responses
curl -L \
  --url '/users/{id}' \
  --header 'Authorization: YOUR_API_KEY'
{
  "id": "text",
  "username": "text",
  "autoGenerated": true,
  "mqttPublishPrefix": "text",
  "identityProvider": "local",
  "grantTypes": [
    {
      "method": "password",
      "isRequired": true
    }
  ],
  "tokens": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text",
      "label": "text"
    }
  ],
  "certificates": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text"
    }
  ],
  "roles": [
    {
      "id": "text",
      "name": "text",
      "isShared": true,
      "permissions": [
        {
          "id": "text",
          "resource": "text",
          "operation": "read",
          "context": "http"
        }
      ],
      "ldapGroupDn": "text",
      "msEntraIdGroupId": "text"
    }
  ],
  "mfa_is_enrolled": true,
  "enforceMFAEnrollment": true
}

User

Update an existing user

put
Authorizations
Path parameters
idanyrequired

Id of user

Body
usernamestring · min: 3optional
passwordstringoptional
mqttPublishPrefixstringoptional
identityProviderstring · enumoptional
Options: local, ldap, msentraid
grantTypesobject[]optional

rolesstring[]optional

An array of roleId of the roles the new user should have. (Must be roleId, not role name.)

permissionsobject[]optional

disableMfabooleanoptional

Indicates that MFA for the given user should be disabled

enforceMFAEnrollmentbooleanoptional

Enforces the user to enroll MFA

Responses
curl -L \
  --request PUT \
  --url '/users/{id}' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "text",
    "password": "text",
    "mqttPublishPrefix": "text",
    "identityProvider": "local",
    "grantTypes": [
      {
        "method": "password",
        "isRequired": true
      }
    ],
    "roles": [
      "text"
    ],
    "permissions": [
      {
        "id": "text",
        "resource": "text",
        "operation": "read",
        "context": "http"
      }
    ],
    "disableMfa": true,
    "enforceMFAEnrollment": true
  }'
{
  "id": "text",
  "username": "text",
  "autoGenerated": true,
  "mqttPublishPrefix": "text",
  "identityProvider": "local",
  "grantTypes": [
    {
      "method": "password",
      "isRequired": true
    }
  ],
  "tokens": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text",
      "label": "text"
    }
  ],
  "certificates": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text"
    }
  ],
  "roles": [
    {
      "id": "text",
      "name": "text",
      "isShared": true,
      "permissions": [
        {
          "id": "text",
          "resource": "text",
          "operation": "read",
          "context": "http"
        }
      ],
      "ldapGroupDn": "text",
      "msEntraIdGroupId": "text"
    }
  ],
  "mfa_is_enrolled": true,
  "enforceMFAEnrollment": true
}

OK

Delete an existing user

delete
Authorizations
Path parameters
idanyrequired

Id of user

Responses
curl -L \
  --request DELETE \
  --url '/users/{id}' \
  --header 'Authorization: YOUR_API_KEY'
No body

OK

Get all tokens generated by this user

get
Authorizations
Path parameters
idanyrequired

Id of user

Responses
curl -L \
  --url '/users/{id}/tokens' \
  --header 'Authorization: YOUR_API_KEY'
[
  {
    "fingerprint": "text",
    "createdAt": "text",
    "expiresAt": "text",
    "label": "text"
  }
]

List of user generated tokens

Delete all tokens generated by this user

delete
Authorizations
Path parameters
idanyrequired

Id of user

Query parameters
tokenIdanyoptional

Id of the Token to be deleted. All tokens for the user are deleted if not present.

Responses
curl -L \
  --request DELETE \
  --url '/users/{id}/tokens' \
  --header 'Authorization: YOUR_API_KEY'
No body

Token(s) deleted

Add a new certificate to a user

post
Authorizations
Path parameters
idanyrequired

Id of user

Body
fingerprintstringrequired
Responses
curl -L \
  --request POST \
  --url '/users/{id}/certificates' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "fingerprint": "text"
  }'
No body

Created

Delete an existing certificate

delete
Authorizations
Path parameters
idanyrequired

Id of user

Body
fingerprintstringrequired
Responses
curl -L \
  --request DELETE \
  --url '/users/{id}/certificates' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "fingerprint": "text"
  }'
No body

OK

Add a new role to a user

post
Authorizations
Path parameters
idanyrequired

Id of user

Body
roleIdstringrequired
Responses
curl -L \
  --request POST \
  --url '/users/{id}/roles' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "roleId": "text"
  }'
No body

Created

Remove a role from a user

delete
Authorizations
Path parameters
idanyrequired

Id of user

Body
roleIdstringrequired
Responses
curl -L \
  --request DELETE \
  --url '/users/{id}/roles' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "roleId": "text"
  }'
No body

OK

Create a new role

post
Authorizations
Body
namestringrequired
isSharedbooleanrequired
autoGeneratedbooleanoptional
permissionsobject[]optional

ldapGroupDnstringoptional
msEntraIdGroupIdsstringoptional

A comma separated list of MS Entra Id groups associated with this role

Responses
curl -L \
  --request POST \
  --url '/roles' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "isShared": true,
    "autoGenerated": true,
    "permissions": [
      {
        "id": "text",
        "resource": "text",
        "operation": "read",
        "context": "http"
      }
    ],
    "ldapGroupDn": "text",
    "msEntraIdGroupIds": "text"
  }'
{
  "id": "text",
  "name": "text",
  "isShared": true,
  "permissions": [
    {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    }
  ],
  "ldapGroupDn": "text",
  "msEntraIdGroupId": "text"
}

Created

List roles

get
Authorizations
Query parameters
name[eq]anyoptional

Filter by equal to name

Responses
curl -L \
  --url '/roles' \
  --header 'Authorization: YOUR_API_KEY'
[
  {
    "id": "text",
    "name": "text",
    "isShared": true,
    "permissions": [
      {
        "id": "text",
        "resource": "text",
        "operation": "read",
        "context": "http"
      }
    ],
    "ldapGroupDn": "text",
    "msEntraIdGroupId": "text"
  }
]

Array of roles

List paginated roles

get
Authorizations
Query parameters
namesanyoptional

Filter by the given names

rowsPerPageanyrequired

Set the page size of the yielded page

pageNumberanyrequired

Set the current page to be retrieved

autoGeneratedanyoptional

Filter by roles that are or not auto generated, defaults to any

isSharedanyoptional

Filter by roles that are or not shared, defaults to any

Responses
curl -L \
  --url '/roles/page' \
  --header 'Authorization: YOUR_API_KEY'
{
  "roles": [
    {
      "id": "text",
      "name": "text",
      "isshared": true,
      "autogenerated": true,
      "users": [
        {
          "id": null,
          "username": null
        }
      ],
      "permissions": [
        {
          "id": null,
          "resource": null,
          "operation": null,
          "context": null
        }
      ],
      "ldapgroupdn": "text",
      "msEntraIdGroupIds": "text"
    }
  ],
  "pagination": {
    "totalPages": 1,
    "totalRows": 1,
    "totalRowsInPage": 1,
    "currentPage": 1,
    "nextPage": 1,
    "rowsPerPage": 1
  }
}

Object with array of roles and pagination information

List roles names

get
Authorizations
Responses
curl -L \
  --url '/roles/names' \
  --header 'Authorization: YOUR_API_KEY'
[
  {
    "id": "text",
    "name": "text"
  }
]

Object with array of roles names and ids

Get a specific role

get
Authorizations
Path parameters
idanyrequired

Id of role

Responses
curl -L \
  --url '/roles/{id}' \
  --header 'Authorization: YOUR_API_KEY'
{
  "id": "text",
  "name": "text",
  "isShared": true,
  "permissions": [
    {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    }
  ],
  "ldapGroupDn": "text",
  "msEntraIdGroupId": "text"
}

Role

Update an existing role

put
Authorizations
Path parameters
idanyrequired

Id of role

Body
namestringrequired
isSharedbooleanoptional
permissionsobject[]optional

ldapGroupDnstringoptional
msEntraIdGroupIdsstringoptional

A comma separated list of MS Entra Id groups associated with this role

Responses
curl -L \
  --request PUT \
  --url '/roles/{id}' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "isShared": true,
    "permissions": [
      {
        "id": "text",
        "resource": "text",
        "operation": "read",
        "context": "http"
      }
    ],
    "ldapGroupDn": "text",
    "msEntraIdGroupIds": "text"
  }'
{
  "id": "text",
  "name": "text",
  "isShared": true,
  "permissions": [
    {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    }
  ],
  "ldapGroupDn": "text",
  "msEntraIdGroupId": "text"
}

OK

Delete an existing role

delete
Authorizations
Path parameters
idanyrequired

Id of role

Responses
curl -L \
  --request DELETE \
  --url '/roles/{id}' \
  --header 'Authorization: YOUR_API_KEY'
No body

OK

List role permissions

get
Authorizations
Path parameters
idanyrequired

Id of role

Responses
curl -L \
  --url '/roles/{id}/permissions' \
  --header 'Authorization: YOUR_API_KEY'
[
  {
    "id": "text",
    "resource": "text",
    "operation": "read",
    "context": "http"
  }
]

Array of permissions

Add a new permission to a role

post
Authorizations
Path parameters
idanyrequired

Id of role

Body
resourcestringrequired
operationstring · enumrequired
Options: read, write, readWrite
contextstring · enumrequired
Options: http, mqtt, control_plane
Responses
curl -L \
  --request POST \
  --url '/roles/{id}/permissions' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "resource": "text",
    "operation": "read",
    "context": "http"
  }'
No body

Created

Update an existing permission

get
Authorizations
Path parameters
idanyrequired

Id of role

pemIdanyrequired

Id of permission

Responses
curl -L \
  --url '/roles/{id}/permissions/{pemId}' \
  --header 'Authorization: YOUR_API_KEY'
{
  "id": "text",
  "resource": "text",
  "operation": "read",
  "context": "http"
}

Permission

Update an existing permission

put
Authorizations
Path parameters
idanyrequired

Id of role

pemIdanyrequired

Id of permission

Body
resourcestringoptional
operationstring · enumrequired
Options: read, write, readWrite
Responses
curl -L \
  --request PUT \
  --url '/roles/{id}/permissions/{pemId}' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "resource": "text",
    "operation": "read"
  }'
No body

OK

Delete an existing permission

delete
Authorizations
Path parameters
idanyrequired

Id of role

pemIdanyrequired

Id of permission

Responses
curl -L \
  --request DELETE \
  --url '/roles/{id}/permissions/{pemId}' \
  --header 'Authorization: YOUR_API_KEY'
No body

OK

Login into the cybus connectware

post
Body
usernamestringrequired
passwordstringrequired
expireTimeInHoursnumberoptional
labelstringoptional
Responses
curl -L \
  --request POST \
  --url '/login' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "text",
    "password": "text",
    "expireTimeInHours": 1,
    "label": "text"
  }'
{
  "token": "text",
  "expiresAt": "text",
  "permissions": [
    {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    }
  ],
  "needsMfa": true,
  "secret": "text",
  "enforceMFAEnrollment": true
}

OK

Return the session of the current user

get
Authorizations
Responses
curl -L \
  --url '/session' \
  --header 'Authorization: YOUR_API_KEY'
{
  "username": "text",
  "expiresAt": "text",
  "permissions": [
    {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    }
  ],
  "mfa": {
    "enabled": true,
    "enforced": true
  }
}

OK

Return the permissions of the current user

get
Authorizations
Responses
curl -L \
  --url '/permissions' \
  --header 'Authorization: YOUR_API_KEY'
No body

OK

Return a page of all permissions

get
Authorizations
Query parameters
idsanyoptional

Filter by the given permission ids

rowsPerPageanyrequired

Set the page size of the yielded page

pageNumberanyrequired

Set the current page to be retrieved

Responses
curl -L \
  --url '/permissions/page' \
  --header 'Authorization: YOUR_API_KEY'
{
  "permissions": [
    {
      "resource": "text",
      "context": "http",
      "usage": [
        {
          "roleName": "text",
          "roleId": "text",
          "isRoleShared": "text",
          "username": null,
          "userId": null,
          "operation": "read"
        }
      ]
    }
  ],
  "pagination": {
    "totalPages": 1,
    "totalRows": 1,
    "totalRowsInPage": 1,
    "currentPage": 1,
    "nextPage": 1,
    "rowsPerPage": 1
  }
}

Object with array of permissions and pagination information

Return all permissions ids

get
Authorizations
Responses
curl -L \
  --url '/permissions/ids' \
  --header 'Authorization: YOUR_API_KEY'
[
  {
    "resource": "text",
    "operation": "read",
    "context": "http",
    "ids": [
      "text"
    ]
  }
]

The ids of all permissions aggregated by resource, operation and context

Logout of the cybus connectware

post
Body
tokenstringrequired
Responses
curl -L \
  --request POST \
  --url '/logout' \
  --header 'Content-Type: application/json' \
  --data '{
    "token": "text"
  }'
No body

OK

Endpoint for self-registration of clients

post
Body
usernamestring · min: 3required

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
passwordstring · min: 5optional

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
csrstringoptional

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=
rolesstring[]optional

Name of roles the user wants to be assigned to

permissionsobject[]optional

Permissions the user wants to be granted individually

contextstringrequired

Free text that helps the granting user understanding where this request comes from.

Example: IoT Device Serial Number <0123456>
Responses
curl -L \
  --request POST \
  --url '/client-registry/register' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "iot.device.0123456",
    "password": "secret-password",
    "csr": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQ3REQ0NBWndDQVFBd2J6RUxN
  QWtHQTFVRUJoTUNSRVV4RHpBTkJnTlZCQWdNQmtKbGNteHBiakVVTUJJRwpBMVVFQ2d3TFVtOWli
  M1J6SUVsdVl5NHhEREFLQmdOVkJBc01BMUltUkRFTk1Bc0dBMVVFQXd3RVVqSkVNakVjCk1Cb0dD
  U3FHU0liM0RRRUpBUllOY2pKa01rQmplV0oxY3k1cGJ6Q0NBU0l3RFFZSktvWklodmNOQVFFQkJR
  QUQKZ2dFUEFEQ0NBUW9DZ2dFQkFNSXlsQmk4azFIZDJseERXZHd5N1Z3WngvaUlrdWpTUUVtWmdk
  Y0JqNk4veTZTSQpiTGMwdFpmK2JGWUZZZ2p0OHRFUUJPRzhNeW94YmYwQSs4T0dHZFJvV3l2eHFt
  ci9TLzhNa1ZGUXJiS2duMDBaCmVrdWlZQVBUOFMvT0FZVnlGT21rWWtWSm0wdkRwMmRkcXRiTUZY
  bXZ1OGxnVnVPckFwMEQ4TjdBcVgwWlUwc0UKZzRmVkdpREtnS040cUFEcXR3aVZKb0dsR0JCYWpm
  ejAxSlhEWnhpUEVac3BYSGJyaVY0Z1JvV0VIVGNGcWc4cgo1WCtZRDlqTGVGdFdRb0g5SHA3ZEFP
  Y1lCRktVRVZjWTlGN20vRWZkVFBwNjNnbTdRdFR4S0EvelIyODRWQUVCCjZFbC8xU2FCME54YlVw
  bHgzVHp4T2ZKYjJpdEd0S1RzN1U2UnF3VUNBd0VBQWFBQU1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0
  SUJBUUIxejdKcGRIRERScTl2WE1BMmNBVVZBRmYvYkRXNzlkNmlMQ0pDVDZ5WlhOcHV0ZXA3N1pQ
  dQpIMSszb08vZmRJdDhaOThjV0J4ZVBNckVDM2krQ0lIdms4a202SVFMVW05cUZVdHRDN0VjUmpU
  UFYwT29vb2l0ClhXOHhzWVhGaEZPTStydTJnbEcrSUVMY3BydS9JamxyVHpwaUtNZVJGQ1FFemww
  WWtZRDZkSk82ME1CRVhjZUgKWHpFZTRtT2oxUDJKNFcycFI1bDFsQjZ5dXB4SWVuRjRhNm5EeFFE
  eFZkcmtBTHNJdDhGZUNTNDNvaHg4NVQ5SApHN2IwOFdmdEFrYzhKR3ZLb00rdE90MzlVZFFESE1S
  OU5QOG9RUUpMaldMcWZRdUtaRmZXNVJyR24zSzA2UGNICkRMN1FNc1hxNFBaMyswUXpCSjZJVGoz
  aUZubHp1VXBqCi0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo=
  ",
    "roles": [
      "manufacturer.iotModule.simpleRole"
    ],
    "permissions": [
      {
        "id": "text",
        "resource": "text",
        "operation": "read",
        "context": "http"
      }
    ],
    "context": "IoT Device Serial Number <0123456>"
  }'
{
  "certificate": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVyVENDQXBXZ0F3SUJBZ0lVS0pYWUpZNWdK\nNExMbHpvSlcvUi9iczMxakw0d0RRWUpLb1pJaHZjTkFRRUYKQlFBd2dZMHhFekFSQmdOVkJBb01D\na041WW5WeklFZHRZa2d4RkRBU0JnTlZCQXNNQzBSbGRtVnNiM0J0Wlc1MApNUjB3R3dZSktvWklo\ndmNOQVFrQkZnNW9aV3hzYjBCamVXSjFjeTVwYnpFUU1BNEdBMVVFQnd3SFNHRnRZblZ5Clp6RVFN\nQTRHQTFVRUNBd0hTR0Z0WW5WeVp6RUxNQWtHQTFVRUJoTUNSRVV4RURBT0JnTlZCQU1NQjBONVlu\nVnoKUTBFd0hoY05Nakl3TlRFMk1URXlNVFU1V2hjTk1qTXdOVEUyTVRFeU1UVTVXakJ2TVFzd0NR\nWURWUVFHRXdKRQpSVEVQTUEwR0ExVUVDQXdHUW1WeWJHbHVNUlF3RWdZRFZRUUtEQXRTYjJKdmRI\nTWdTVzVqTGpFTU1Bb0dBMVVFCkN3d0RVaVpFTVEwd0N3WURWUVFEREFSU01rUXlNUnd3R2dZSktv\nWklodmNOQVFrQkZnMXlNbVF5UUdONVluVnoKTG1sdk1JSUJJakFOQmdrcWhraUc5dzBCQVFFRkFB\nT0NBUThBTUlJQkNnS0NBUUVBd2pLVUdMeVRVZDNhWEVOWgozREx0WEJuSCtJaVM2TkpBU1ptQjF3\nR1BvMy9McEloc3R6UzFsLzVzVmdWaUNPM3kwUkFFNGJ3ektqRnQvUUQ3Cnc0WVoxR2hiSy9HcWF2\nOUwvd3lSVVZDdHNxQ2ZUUmw2UzZKZ0E5UHhMODRCaFhJVTZhUmlSVW1iUzhPbloxMnEKMXN3VmVh\nKzd5V0JXNDZzQ25RUHczc0NwZlJsVFN3U0RoOVVhSU1xQW8zaW9BT3EzQ0pVbWdhVVlFRnFOL1BU\nVQpsY05uR0k4Um15bGNkdXVKWGlCR2hZUWROd1dxRHl2bGY1Z1AyTXQ0VzFaQ2dmMGVudDBBNXhn\nRVVwUVJWeGowClh1YjhSOTFNK25yZUNidEMxUEVvRC9OSGJ6aFVBUUhvU1gvVkpvSFEzRnRTbVhI\nZFBQRTU4bHZhSzBhMHBPenQKVHBHckJRSURBUUFCb3lJd0lEQUpCZ05WSFJNRUFqQUFNQk1HQTFV\nZEpRUU1NQW9HQ0NzR0FRVUZCd01DTUEwRwpDU3FHU0liM0RRRUJCUVVBQTRJQ0FRQmpkWGtBaUtJ\nWUd0Q3RIMDVwck1hbWhZSHl3cFNYdzBPSzB4bTBMcFlTCkpvc094OWFGVjRqcS9Fb3NlWlZndkR0\nOGM0ajlXVlBkQ1lmOHlwaHVFRS8yM2s3akEzaFlYZmFIZnVoenZnaWgKSDB3U0Q2WmgrNGptaDdE\nV0tEVnRwOWI4aFBmdytzR3ltYUtkaWM4WFNVMlNDK1RMNGRYTkFlTjFIeVVtanltcApRZFZBamsx\nQXNRT3YvU0gzaEg4cmJBWEprMWpoTks0Z2tGT0oxTHJ5TkR3dmNPc3JHbFpLY3BsWStKVE1HZkFH\nCjUyYmFtdGpIVG9FQ1BSOGhIeGx6bTlFYUxidUtpUlpwZ242M25qYWRWK1d4a09zVTlPSUM3dm9U\nSlNtQ3VOZmkKdjh1RmdsSUFGS0JXSmVOZERxQk5OZnBjTU5GTDV0R1NIbzkvVEtLQ3hEam1QN3Ns\nc3BRMzVYTFluODl1MjY3agpJZmU2dkppdXZxdXdyN0c1S1orTTkvQitlWk5ISHVrNEFDTUs5OFk1\ncWhtb2pQS3p5Z202b2FiRzI3bk1EYzF5CkM0Q05LUWUrL1J5SEdYbXFjdm5ZVGxHVGpNWktoRWpX\nOVp3UmJyZVZ1M1lmNVhlZU95OXNpOWs5VTI3bVQ0UTUKdC8zU2xCK2JiTW4vbzVPWFI0YStnT2VX\nVWVJRzl6SzNvYVdXbmVKVlZPdmRlQy8xTjY0ajRERjlKWm45cGtENgowdUozQUFKMUYvN2tJa2tT\nMXNmZWdjejZCU2pkMldkQjhHaDZSN1ZVS0VPSEpCREphZm1EdkRjVGdSZytQa1NUCmpjdHVzVnNl\nYi9lcE1BRkQ1dERuUDFHVU8yYkx2dzQ3QWl0akxKdnljeUZZbnovU1ZFK2dXOTU3ZEpXcVVjZEkK\nYXc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCgo=\n"
}

Granted. The registration request has been confirmed, proceed to login

Receive a list of all pending registration requests

get
Authorizations
Responses
curl -L \
  --url '/client-registry' \
  --header 'Authorization: YOUR_API_KEY'
[
  {
    "timestamp": "2022-03-25T17:25:21.379Z",
    "username": "iot.device.0123456",
    "credentialType": "certificate",
    "roles": [
      "text"
    ],
    "context": "IoT Device Serial Number <0123456>",
    "permissions": {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    },
    "granted": true
  }
]

OK

Return the current lock status of the registration endpoint

get
Authorizations
Responses
curl -L \
  --url '/client-registry/status' \
  --header 'Authorization: YOUR_API_KEY'
{
  "status": "open",
  "unlockedUntil": 1
}

OK

Open the registration endpoint temporarily

post
Authorizations
Body
durationintegeroptional

This parameter defines how long the registration endpoint will be kept open (in milliseconds). Default if undefined: 30000 milliseconds

Example: 30000
Responses
curl -L \
  --request POST \
  --url '/client-registry/open' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "duration": 30000
  }'
No body

OK

Lock the registration endpoint now. This will flush the internal request cache.

post
Authorizations
Responses
curl -L \
  --request POST \
  --url '/client-registry/lock' \
  --header 'Authorization: YOUR_API_KEY'
No body

OK

Confirm a single authentication request

post
Authorizations
Body
usernamestring · min: 3required

Username to confirm. Must match a username that is currently in the pendingRequests list.

mqttPublishPrefixstringoptional
grantTypesobject[]optional

initialPermissionsobject[]optional

rolesstring[]optional

An array of roleId of the roles the new user should have. (Must be roleId, not role name.)

Responses
curl -L \
  --request POST \
  --url '/client-registry/confirm' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "text",
    "mqttPublishPrefix": "text",
    "grantTypes": [
      {
        "method": "password",
        "isRequired": true
      }
    ],
    "initialPermissions": [
      {
        "id": "text",
        "resource": "text",
        "operation": "read",
        "context": "http"
      }
    ],
    "roles": [
      "text"
    ]
  }'
{
  "id": "text",
  "username": "text",
  "autoGenerated": true,
  "mqttPublishPrefix": "text",
  "identityProvider": "local",
  "grantTypes": [
    {
      "method": "password",
      "isRequired": true
    }
  ],
  "tokens": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text",
      "label": "text"
    }
  ],
  "certificates": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text"
    }
  ],
  "roles": [
    {
      "id": "text",
      "name": "text",
      "isShared": true,
      "permissions": [
        {
          "id": "text",
          "resource": "text",
          "operation": "read",
          "context": "http"
        }
      ],
      "ldapGroupDn": "text",
      "msEntraIdGroupId": "text"
    }
  ],
  "mfa_is_enrolled": true,
  "enforceMFAEnrollment": true
}

OK

List certificates

get
Authorizations
Responses
curl -L \
  --url '/certificates' \
  --header 'Authorization: YOUR_API_KEY'
[
  {
    "id": "text",
    "issuedBy": {
      "commonName": "text",
      "organization": "text",
      "organizationalUnit": "text"
    },
    "issuedTo": {
      "commonName": "text",
      "organization": "text",
      "organizationalUnit": "text",
      "alternativeNames": [
        "text"
      ]
    },
    "keyUsage": [
      "text"
    ],
    "extendedKeyUsage": [
      "text"
    ],
    "basicConstraints": {
      "isCA": true,
      "pathLength": 1
    },
    "issuedOn": 1,
    "expiresOn": 1,
    "fingerprints": {
      "sha1": "text",
      "sha256": "text"
    },
    "removable": true
  }
]

Array of certficates

Deletes certificate

delete
Authorizations
Query parameters
idanyrequired

Id of certificate

Responses
curl -L \
  --request DELETE \
  --url '/certificates' \
  --header 'Authorization: YOUR_API_KEY'
No body

OK

Add certificate

post
Authorizations
Body
stringoptional
Responses
curl -L \
  --request POST \
  --url '/certificates' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '"text"'
[
  {
    "id": "text",
    "issuedBy": {
      "commonName": "text",
      "organization": "text",
      "organizationalUnit": "text"
    },
    "issuedTo": {
      "commonName": "text",
      "organization": "text",
      "organizationalUnit": "text",
      "alternativeNames": [
        "text"
      ]
    },
    "keyUsage": [
      "text"
    ],
    "extendedKeyUsage": [
      "text"
    ],
    "basicConstraints": {
      "isCA": true,
      "pathLength": 1
    },
    "issuedOn": 1,
    "expiresOn": 1,
    "fingerprints": {
      "sha1": "text",
      "sha256": "text"
    },
    "removable": true
  }
]

Array of added certficates

Returns given certificate content

get
Authorizations
Query parameters
idanyrequired

Id of certificate

Responses
curl -L \
  --url '/certificates/content' \
  --header 'Authorization: YOUR_API_KEY'
text

Certificate content

Enhanced authentication of MQTT5 (not supported)

post
Body
client_idstringoptional
propertiesobjectoptional

Responses
curl -L \
  --request POST \
  --url '/broker/auth/enhanced' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "text",
    "properties": {
      "p_authentication_method": "text"
    }
  }'
{
  "result": "text",
  "modifiers": {
    "max_message_size": "text",
    "max_inflight_messages": "text",
    "retry_interval": "text"
  }
}

OK

Return a password policy rules

get
Authorizations
Responses
curl -L \
  --url '/policy/password' \
  --header 'Authorization: YOUR_API_KEY'
{
  "min": 1,
  "lower": 1,
  "upper": 1,
  "numeric": 1,
  "symbol": 1
}

OK

Return a database maintenance status

get
Authorizations
Responses
curl -L \
  --url '/maintenance/db' \
  --header 'Authorization: YOUR_API_KEY'
{
  "running": true,
  "backup": {
    "id": "text",
    "succeeded": true,
    "statusMessage": "text",
    "startDate": "2025-03-30T00:15:37.217Z",
    "endDate": "2025-03-30T00:15:37.217Z"
  },
  "restore": {
    "id": "text",
    "succeeded": true,
    "statusMessage": "text",
    "startDate": "2025-03-30T00:15:37.217Z",
    "endDate": "2025-03-30T00:15:37.217Z"
  }
}

OK

Download a database backup

get
Authorizations
Responses
curl -L \
  --url '/maintenance/db/backup' \
  --header 'Authorization: YOUR_API_KEY'
text

OK

Start a database backup

post
Authorizations
Responses
curl -L \
  --request POST \
  --url '/maintenance/db/backup' \
  --header 'Authorization: YOUR_API_KEY'
text

Accepted. Database backup started.

Upload archive and start database restore

post
Authorizations
Responses
curl -L \
  --request POST \
  --url '/maintenance/db/restore' \
  --header 'Authorization: YOUR_API_KEY'
No body

Accepted. The archive is uploaded, and the database restores process starts.

Enable MFA for an existing user

post
Authorizations
Responses
curl -L \
  --request POST \
  --url '/mfa/enable' \
  --header 'Authorization: YOUR_API_KEY'
{
  "uri": "otpauth://totp/Cybus:Connectware?issuer=Cybus&secret=something&algorithm=SHA1&digits=6&period=30"
}

ok

Validate MFA enrollment of the user

post
Authorizations
Body
otpstringrequired
Responses
curl -L \
  --request POST \
  --url '/mfa/validate' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "otp": "text"
  }'
{
  "backupCodes": [
    "text"
  ]
}

ok

Login user with MFA

post
Authorizations
Body
usernamestringrequired
otpstringoptional
backupCodestringoptional
secretstringrequired
Responses
curl -L \
  --request POST \
  --url '/mfa/login' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "text",
    "otp": "text",
    "backupCode": "text",
    "secret": "text"
  }'
{
  "token": "text",
  "expiresAt": "text",
  "permissions": [
    {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    }
  ],
  "needsMfa": true,
  "secret": "text",
  "enforceMFAEnrollment": true
}

ok

User self de-registration from MFA

post
Authorizations
Body
otpstringoptional
backupCodestringoptional
Responses
curl -L \
  --request POST \
  --url '/mfa/disable' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "otp": "text",
    "backupCode": "text"
  }'
No body

ok

Regenarete backup codes a user

post
Authorizations
Body
otpstringoptional
backupCodestringoptional
Responses
curl -L \
  --request POST \
  --url '/mfa/regenerate/backupcodes' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "otp": "text",
    "backupCode": "text"
  }'
{
  "backupCodes": [
    "text"
  ]
}

ok

Checks if a user is enrolled to mfa or not

get
Authorizations
Responses
curl -L \
  --url '/mfa/isenrolled' \
  --header 'Authorization: YOUR_API_KEY'
{
  "isEnrolled": true
}

ok

Redirects the client that accesses this path to the MS Entra ID login page

get
Header parameters
refereranyoptional

See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer. If given, will be used as the redirection in case of internal error during URL generation

Responses
curl -L \
  --url '/msEntraId/login'
No body

In case of success or failure, redirects to the URL the client ought to be sent to

Landing endpoint after user is done authenticating with MS Entra ID

get
Query parameters
codeanyrequired

The access code provided by MS Entra ID that can be exchanged for Access and ID Tokens.

stateanyrequired

State is a security parameter used to verify that the response is initiated from CW, preventing CSRF attacks.

Responses
curl -L \
  --url '/msEntraId/redirect'
No body

OK. Redirecting to Admin UI

PreviousAPI ReferenceNextClient Registry (API)

Last updated

Was this helpful?