API Definition

81KB

Auth-Server Schema.yaml

LDAP configuration

get

/auth/ldap

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/auth/ldap' \
  --header 'Authorization: YOUR_API_KEY'

200

200

{
  "enabled": false,
  "mode": "GROUP"
}

LDAP configuration

MFA configuration

get

/auth/mfa

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/auth/mfa' \
  --header 'Authorization: YOUR_API_KEY'

200

200

{
  "enabled": false
}

MFA configuration

Create a new user

post

/users

Authorizations

Body

usernamestring · min: 3required

autoGeneratedboolean

mqttPublishPrefixstring

passwordstring · min: 5

identityProviderstring · enumrequired

Options: local, ldap

enforceMFAEnrollmentboolean

grantTypesobject[]required

certificatesobject[]

initialPermissionsobject[]

rolesstring[]

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/users' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"username":"text","autoGenerated":false,"identityProvider":"local","enforceMFAEnrollment":false,"grantTypes":[{"method":"password"}],"certificates":[{}],"initialPermissions":[{"operation":"read","context":"http"}],"roles":[null]}'

201

400

201

{
  "id": "text",
  "username": "text",
  "autoGenerated": true,
  "mqttPublishPrefix": "text",
  "identityProvider": "local",
  "mfa_is_enrolled": true,
  "enforceMFAEnrollment": true,
  "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"
        }
      ]
    }
  ]
}

Created

List users

get

/listUsers

Authorizations

Query parameters

username[eq]string[]

The optional list to be matched against the usernames

pageNumberinteger

The page number to fetch, starts at page 1

rowsPerPageinteger · max: 100

The number of records per page to return

excludeAutoGeneratedboolean

If the auto generated roles should be excluded from the results

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/listUsers' \
  --header 'Authorization: YOUR_API_KEY'

200

400

200

{
  "pagination": {
    "totalPages": 1,
    "totalRows": 1,
    "totalRowsInPage": 1,
    "currentPage": 1,
    "nextPage": 1,
    "rowsPerPage": 1
  },
  "users": [
    {
      "id": "text",
      "username": "text",
      "autoGenerated": true,
      "mqttPublishPrefix": "text",
      "identityProvider": "local",
      "mfa_is_enrolled": true,
      "enforceMFAEnrollment": true,
      "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"
            }
          ]
        }
      ]
    }
  ]
}

Object with array of users and pagination information

List all usernames

get

/users/usernames

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/users/usernames' \
  --header 'Authorization: YOUR_API_KEY'

200

200

[
  {
    "username": "text",
    "id": "text"
  }
]

Array of user ids

List user ids

get

/users/ids

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/users/ids' \
  --header 'Authorization: YOUR_API_KEY'

200

200

[
  "text"
]

Array of user ids

Create new users in batch

post

/users/batch

Authorizations

Body

usernamestring · min: 3required

autoGeneratedboolean

mqttPublishPrefixstring

passwordstring · min: 5

identityProviderstring · enumrequired

Options: local, ldap

enforceMFAEnrollmentboolean

grantTypesobject[]required

certificatesobject[]

initialPermissionsobject[]

rolesstring[]

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/users/batch' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '[{"username":"text","autoGenerated":false,"identityProvider":"local","enforceMFAEnrollment":false,"grantTypes":[{"method":"password"}],"certificates":[{}],"initialPermissions":[{"operation":"read","context":"http"}],"roles":[null]}]'

201

400

201

[
  "text"
]

Created

Delete users in batch

post

/users/batch/delete

Authorizations

Body

itemsstring

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/users/batch/delete' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '[null]'

200

400

200

No body

ok

Change user password

put

/users/change-password

Authorizations

Body

passwordstring

newPasswordstring · min: 5

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url '/api/users/change-password' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json'

204

400

204

No body

Changed

Get a specific user

get

/users/{id}

Authorizations

Path parameters

idstringrequired

Id of user

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/users/{id}' \
  --header 'Authorization: YOUR_API_KEY'

200

404

200

{
  "id": "text",
  "username": "text",
  "autoGenerated": true,
  "mqttPublishPrefix": "text",
  "identityProvider": "local",
  "mfa_is_enrolled": true,
  "enforceMFAEnrollment": true,
  "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"
        }
      ]
    }
  ]
}

User

Update an existing user

put

/users/{id}

Authorizations

Path parameters

idstringrequired

Id of user

Body

usernamestring · min: 3

passwordstring

mqttPublishPrefixstring

identityProviderstring · enum

Options: local, ldap

disableMfaboolean

Indicates that MFA for the given user should be disabled

enforceMFAEnrollmentboolean

Enforces the user to enroll MFA

grantTypesobject[]

rolesstring[]

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

permissionsobject[]

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url '/api/users/{id}' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"identityProvider":"local","grantTypes":[{"method":"password"}],"roles":[null],"permissions":[{"operation":"read","context":"http"}]}'

200

400

404

200

{
  "id": "text",
  "username": "text",
  "autoGenerated": true,
  "mqttPublishPrefix": "text",
  "identityProvider": "local",
  "mfa_is_enrolled": true,
  "enforceMFAEnrollment": true,
  "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"
        }
      ]
    }
  ]
}

OK

Delete an existing user

delete

/users/{id}

Authorizations

Path parameters

idstringrequired

Id of user

Responses

cURL

JavaScript

Python

HTTP

cURL

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

200

404

409

200

No body

OK

Get all tokens generated by this user

get

/users/{id}/tokens

Authorizations

Path parameters

idstringrequired

Id of user

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/users/{id}/tokens' \
  --header 'Authorization: YOUR_API_KEY'

200

404

200

[
  {
    "fingerprint": "text",
    "createdAt": "text",
    "expiresAt": "text",
    "label": "text"
  }
]

List of user generated tokens

Delete all tokens generated by this user

delete

/users/{id}/tokens

Authorizations

Path parameters

idstringrequired

Id of user

Query parameters

tokenIdstring

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

Responses

cURL

JavaScript

Python

HTTP

cURL

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

200

404

200

No body

Token(s) deleted

Add a new certificate to a user

post

/users/{id}/certificates

Authorizations

Path parameters

idstringrequired

Id of user

Body

fingerprintstringrequired

Responses

cURL

JavaScript

Python

HTTP

cURL

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

201

400

201

No body

Created

Delete an existing certificate

delete

/users/{id}/certificates

Authorizations

Path parameters

idstringrequired

Id of user

Body

fingerprintstringrequired

Responses

cURL

JavaScript

Python

HTTP

cURL

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

200

400

404

200

No body

OK

Add a new role to a user

post

/users/{id}/roles

Authorizations

Path parameters

idstringrequired

Id of user

Body

roleIdstringrequired

Responses

cURL

JavaScript

Python

HTTP

cURL

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

201

400

404

201

No body

Created

Remove a role from a user

delete

/users/{id}/roles

Authorizations

Path parameters

idstringrequired

Id of user

Body

roleIdstringrequired

Responses

cURL

JavaScript

Python

HTTP

cURL

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

200

400

404

409

200

No body

OK

Create a new role

post

/roles

Authorizations

Body

namestringrequired

isSharedbooleanrequired

autoGeneratedboolean

permissionsobject[]

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

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

201

400

201

{
  "id": "text",
  "name": "text",
  "isShared": true,
  "permissions": [
    {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    }
  ]
}

Created

List roles

get

/roles

Authorizations

Query parameters

name[eq]string

Filter by equal to name

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/roles' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

200

[
  {
    "id": "text",
    "name": "text",
    "isShared": true,
    "permissions": [
      {
        "id": "text",
        "resource": "text",
        "operation": "read",
        "context": "http"
      }
    ]
  }
]

Array of roles

List paginated roles

get

/roles/page

Authorizations

Query parameters

namesstring[]

Filter by the given names

rowsPerPageinteger · min: 1 · max: 50required

Set the page size of the yielded page

pageNumberinteger · min: 1required

Set the current page to be retrieved

autoGeneratedboolean

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

isSharedboolean

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/roles/page?rowsPerPage=1&pageNumber=1' \
  --header 'Authorization: YOUR_API_KEY'

200

400

401

403

200

{
  "pagination": {
    "totalPages": 1,
    "totalRows": 1,
    "totalRowsInPage": 1,
    "currentPage": 1,
    "nextPage": 1,
    "rowsPerPage": 1
  },
  "roles": [
    {
      "id": "text",
      "name": "text",
      "isshared": true,
      "autogenerated": true,
      "users": [
        {
          "id": null,
          "username": null
        }
      ],
      "permissions": [
        {
          "id": null,
          "resource": null,
          "operation": null,
          "context": null
        }
      ]
    }
  ]
}

Object with array of roles and pagination information

List roles names

get

/roles/names

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/roles/names' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

200

[
  {
    "id": "text",
    "name": "text"
  }
]

Object with array of roles names and ids

Get a specific role

get

/roles/{id}

Authorizations

Path parameters

idstringrequired

Id of role

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/roles/{id}' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

200

{
  "id": "text",
  "name": "text",
  "isShared": true,
  "permissions": [
    {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    }
  ]
}

Role

Update an existing role

put

/roles/{id}

Authorizations

Path parameters

idstringrequired

Id of role

Body

namestringrequired

isSharedboolean

permissionsobject[]

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

400

404

200

{
  "id": "text",
  "name": "text",
  "isShared": true,
  "permissions": [
    {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    }
  ]
}

OK

Delete an existing role

delete

/roles/{id}

Authorizations

Path parameters

idstringrequired

Id of role

Responses

cURL

JavaScript

Python

HTTP

cURL

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

200

400

404

409

200

No body

OK

List role permissions

get

/roles/{id}/permissions

Authorizations

Path parameters

idstringrequired

Id of role

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/roles/{id}/permissions' \
  --header 'Authorization: YOUR_API_KEY'

200

401

403

404

200

[
  {
    "id": "text",
    "resource": "text",
    "operation": "read",
    "context": "http"
  }
]

Array of permissions

Add a new permission to a role

post

/roles/{id}/permissions

Authorizations

Path parameters

idstringrequired

Id of role

Body

resourcestringrequired

operationstring · enumrequired

Options: read, write, readWrite

contextstring · enumrequired

Options: http, mqtt

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/roles/{id}/permissions' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"resource":"text","operation":"read","context":"http"}'

201

400

409

201

No body

Created

Update an existing permission

get

/roles/{id}/permissions/{pemId}

Authorizations

Path parameters

idstringrequired

Id of role

pemIdstringrequired

Id of permission

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/roles/{id}/permissions/{pemId}' \
  --header 'Authorization: YOUR_API_KEY'

200

400

404

200

{
  "id": "text",
  "resource": "text",
  "operation": "read",
  "context": "http"
}

Permission

Update an existing permission

put

/roles/{id}/permissions/{pemId}

Authorizations

Path parameters

idstringrequired

Id of role

pemIdstringrequired

Id of permission

Body

resourcestring

operationstring · enumrequired

Options: read, write, readWrite

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url '/api/roles/{id}/permissions/{pemId}' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"operation":"read"}'

200

400

404

200

No body

OK

Delete an existing permission

delete

/roles/{id}/permissions/{pemId}

Authorizations

Path parameters

idstringrequired

Id of role

pemIdstringrequired

Id of permission

Responses

cURL

JavaScript

Python

HTTP

cURL

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

200

400

404

200

No body

OK

Login into the cybus connectware

post

/login

Body

usernamestringrequired

passwordstringrequired

expireTimeInHoursnumber

labelstring

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/login' \
  --header 'Content-Type: application/json' \
  --data '{"username":"text","password":"text"}'

200

400

403

200

{
  "token": "text",
  "expiresAt": "text",
  "needsMfa": true,
  "secret": "text",
  "enforceMFAEnrollment": true,
  "permissions": [
    {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    }
  ]
}

OK

Return the session of the current user

get

/session

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/session' \
  --header 'Authorization: YOUR_API_KEY'

200

401

200

{
  "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

/permissions

Authorizations

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/permissions' \
  --header 'Authorization: YOUR_API_KEY'

200

401

200

No body

OK

Return a page of all permissions

get

/permissions/page

Authorizations

Query parameters

idsstring[]

Filter by the given permission ids

rowsPerPageinteger · min: 1 · max: 50required

Set the page size of the yielded page

pageNumberinteger · min: 1required

Set the current page to be retrieved

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/permissions/page?rowsPerPage=1&pageNumber=1' \
  --header 'Authorization: YOUR_API_KEY'

200

400

401

200

{
  "pagination": {
    "totalPages": 1,
    "totalRows": 1,
    "totalRowsInPage": 1,
    "currentPage": 1,
    "nextPage": 1,
    "rowsPerPage": 1
  },
  "permissions": [
    {
      "resource": "text",
      "context": "http",
      "usage": [
        {
          "roleName": "text",
          "roleId": "text",
          "isRoleShared": "text",
          "operation": "read",
          "username": null,
          "userId": null
        }
      ]
    }
  ]
}

Object with array of permissions and pagination information

Return all permissions ids

get

/permissions/ids

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/permissions/ids' \
  --header 'Authorization: YOUR_API_KEY'

200

401

200

[
  {
    "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

/logout

Body

tokenstringrequired

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/logout' \
  --header 'Content-Type: application/json' \
  --data '{"token":"text"}'

200

400

404

200

No body

OK

Endpoint for self-registration of clients

post

/client-registry/register

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: 5

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

csrstring

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=

contextstringrequired

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

Example: IoT Device Serial Number <0123456>

rolesstring[]

Name of roles the user wants to be assigned to

permissionsobject[]

Permissions the user wants to be granted individually

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/client-registry/register' \
  --header 'Content-Type: application/json' \
  --data '{"username":"iot.device.0123456","password":"secret-password","csr":"LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQ3REQ0NBWndDQVFBd2J6RUxN\nQWtHQTFVRUJoTUNSRVV4RHpBTkJnTlZCQWdNQmtKbGNteHBiakVVTUJJRwpBMVVFQ2d3TFVtOWli\nM1J6SUVsdVl5NHhEREFLQmdOVkJBc01BMUltUkRFTk1Bc0dBMVVFQXd3RVVqSkVNakVjCk1Cb0dD\nU3FHU0liM0RRRUpBUllOY2pKa01rQmplV0oxY3k1cGJ6Q0NBU0l3RFFZSktvWklodmNOQVFFQkJR\nQUQKZ2dFUEFEQ0NBUW9DZ2dFQkFNSXlsQmk4azFIZDJseERXZHd5N1Z3WngvaUlrdWpTUUVtWmdk\nY0JqNk4veTZTSQpiTGMwdFpmK2JGWUZZZ2p0OHRFUUJPRzhNeW94YmYwQSs4T0dHZFJvV3l2eHFt\nci9TLzhNa1ZGUXJiS2duMDBaCmVrdWlZQVBUOFMvT0FZVnlGT21rWWtWSm0wdkRwMmRkcXRiTUZY\nbXZ1OGxnVnVPckFwMEQ4TjdBcVgwWlUwc0UKZzRmVkdpREtnS040cUFEcXR3aVZKb0dsR0JCYWpm\nejAxSlhEWnhpUEVac3BYSGJyaVY0Z1JvV0VIVGNGcWc4cgo1WCtZRDlqTGVGdFdRb0g5SHA3ZEFP\nY1lCRktVRVZjWTlGN20vRWZkVFBwNjNnbTdRdFR4S0EvelIyODRWQUVCCjZFbC8xU2FCME54YlVw\nbHgzVHp4T2ZKYjJpdEd0S1RzN1U2UnF3VUNBd0VBQWFBQU1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0\nSUJBUUIxejdKcGRIRERScTl2WE1BMmNBVVZBRmYvYkRXNzlkNmlMQ0pDVDZ5WlhOcHV0ZXA3N1pQ\ndQpIMSszb08vZmRJdDhaOThjV0J4ZVBNckVDM2krQ0lIdms4a202SVFMVW05cUZVdHRDN0VjUmpU\nUFYwT29vb2l0ClhXOHhzWVhGaEZPTStydTJnbEcrSUVMY3BydS9JamxyVHpwaUtNZVJGQ1FFemww\nWWtZRDZkSk82ME1CRVhjZUgKWHpFZTRtT2oxUDJKNFcycFI1bDFsQjZ5dXB4SWVuRjRhNm5EeFFE\neFZkcmtBTHNJdDhGZUNTNDNvaHg4NVQ5SApHN2IwOFdmdEFrYzhKR3ZLb00rdE90MzlVZFFESE1S\nOU5QOG9RUUpMaldMcWZRdUtaRmZXNVJyR24zSzA2UGNICkRMN1FNc1hxNFBaMyswUXpCSjZJVGoz\naUZubHp1VXBqCi0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo=\n","context":"IoT Device Serial Number <0123456>","roles":["manufacturer.iotModule.simpleRole"],"permissions":[{"operation":"read","context":"http"}]}'

201

202

400

409

422

423

201

{
  "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

/client-registry

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/client-registry' \
  --header 'Authorization: YOUR_API_KEY'

200

401

200

[
  {
    "timestamp": "2022-03-25T17:25:21.379Z",
    "username": "iot.device.0123456",
    "context": "IoT Device Serial Number <0123456>",
    "permissions": {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    },
    "granted": true,
    "credentialType": "certificate",
    "roles": [
      "text"
    ]
  }
]

OK

Return the current lock status of the registration endpoint

get

/client-registry/status

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/client-registry/status' \
  --header 'Authorization: YOUR_API_KEY'

200

200

{
  "unlockedUntil": 1,
  "status": "open"
}

OK

Open the registration endpoint temporarily

post

/client-registry/open

Authorizations

Body

durationinteger

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

Example: 30000

Responses

cURL

JavaScript

Python

HTTP

cURL

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

204

401

204

No body

OK

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

post

/client-registry/lock

Authorizations

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/client-registry/lock' \
  --header 'Authorization: YOUR_API_KEY'

204

401

204

No body

OK

Confirm a single authentication request

post

/client-registry/confirm

Authorizations

Body

usernamestring · min: 3required

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

mqttPublishPrefixstring

grantTypesobject[]

initialPermissionsobject[]

rolesstring[]

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/client-registry/confirm' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"username":"text","grantTypes":[{"method":"password"}],"initialPermissions":[{"operation":"read","context":"http"}],"roles":[null]}'

204

401

404

204

{
  "id": "text",
  "username": "text",
  "autoGenerated": true,
  "mqttPublishPrefix": "text",
  "identityProvider": "local",
  "mfa_is_enrolled": true,
  "enforceMFAEnrollment": true,
  "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"
        }
      ]
    }
  ]
}

OK

List certificates

get

/certificates

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/certificates' \
  --header 'Authorization: YOUR_API_KEY'

200

500

200

[
  {
    "id": "text",
    "issuedOn": 1,
    "expiresOn": 1,
    "removable": true,
    "keyUsage": [
      "text"
    ],
    "extendedKeyUsage": [
      "text"
    ],
    "issuedBy": {
      "commonName": "text",
      "organization": "text",
      "organizationalUnit": "text"
    },
    "basicConstraints": {
      "isCA": true,
      "pathLength": 1
    },
    "fingerprints": {
      "sha1": "text",
      "sha256": "text"
    },
    "issuedTo": {
      "commonName": "text",
      "organization": "text",
      "organizationalUnit": "text",
      "alternativeNames": [
        "text"
      ]
    }
  }
]

Array of certficates

Deletes certificate

delete

/certificates

Authorizations

Query parameters

idstringrequired

Id of certificate

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url '/api/certificates?id=text' \
  --header 'Authorization: YOUR_API_KEY'

200

400

404

500

200

No body

OK

Add certificate

post

/certificates

Authorizations

Body

string

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/certificates' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json'

201

400

201

[
  {
    "id": "text",
    "issuedOn": 1,
    "expiresOn": 1,
    "removable": true,
    "keyUsage": [
      "text"
    ],
    "extendedKeyUsage": [
      "text"
    ],
    "issuedBy": {
      "commonName": "text",
      "organization": "text",
      "organizationalUnit": "text"
    },
    "basicConstraints": {
      "isCA": true,
      "pathLength": 1
    },
    "fingerprints": {
      "sha1": "text",
      "sha256": "text"
    },
    "issuedTo": {
      "commonName": "text",
      "organization": "text",
      "organizationalUnit": "text",
      "alternativeNames": [
        "text"
      ]
    }
  }
]

Array of added certficates

Returns given certificate content

get

/certificates/content

Authorizations

Query parameters

idstringrequired

Id of certificate

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/certificates/content?id=text' \
  --header 'Authorization: YOUR_API_KEY'

200

400

404

500

200

text

Certificate content

Enhanced authentication of MQTT5 (not supported)

post

/broker/auth/enhanced

Body

client_idstring

propertiesobject

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/broker/auth/enhanced' \
  --header 'Content-Type: application/json' \
  --data '{"properties":{}}'

200

200

{
  "result": "text",
  "modifiers": {
    "max_message_size": "text",
    "max_inflight_messages": "text",
    "retry_interval": "text"
  }
}

OK

Return a password policy rules

get

/policy/password

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/policy/password' \
  --header 'Authorization: YOUR_API_KEY'

200

200

{
  "min": 1,
  "lower": 1,
  "upper": 1,
  "numeric": 1,
  "symbol": 1
}

OK

Return a database maintenance status

get

/maintenance/db

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/maintenance/db' \
  --header 'Authorization: YOUR_API_KEY'

200

200

{
  "running": true,
  "backup": {
    "id": "text",
    "succeeded": true,
    "statusMessage": "text",
    "startDate": "2025-02-20T19:56:51.886Z",
    "endDate": "2025-02-20T19:56:51.886Z"
  },
  "restore": {
    "id": "text",
    "succeeded": true,
    "statusMessage": "text",
    "startDate": "2025-02-20T19:56:51.886Z",
    "endDate": "2025-02-20T19:56:51.886Z"
  }
}

OK

Download a database backup

get

/maintenance/db/backup

Authorizations

Responses

application/gzip

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/maintenance/db/backup' \
  --header 'Authorization: YOUR_API_KEY'

200

423

200

text

OK

Start a database backup

post

/maintenance/db/backup

Authorizations

Responses

multipart/form-data

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/maintenance/db/backup' \
  --header 'Authorization: YOUR_API_KEY'

202

423

202

text

Accepted. Database backup started.

Upload archive and start database restore

post

/maintenance/db/restore

Authorizations

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/maintenance/db/restore' \
  --header 'Authorization: YOUR_API_KEY'

202

423

202

No body

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

Enable MFA for an existing user

post

/mfa/enable

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/mfa/enable' \
  --header 'Authorization: YOUR_API_KEY'

200

400

409

500

200

{
  "uri": "otpauth://totp/Cybus:Connectware?issuer=Cybus&secret=something&algorithm=SHA1&digits=6&period=30"
}

ok

Validate MFA enrollment of the user

post

/mfa/validate

Authorizations

Body

otpstringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/mfa/validate' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"otp":"text"}'

200

400

401

500

200

{
  "backupCodes": [
    "text"
  ]
}

ok

Login user with MFA

post

/mfa/login

Authorizations

Body

usernamestringrequired

otpstring

backupCodestring

secretstringrequired

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/mfa/login' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"username":"text","secret":"text"}'

200

400

401

403

500

200

{
  "token": "text",
  "expiresAt": "text",
  "needsMfa": true,
  "secret": "text",
  "enforceMFAEnrollment": true,
  "permissions": [
    {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    }
  ]
}

ok

User self de-registration from MFA

post

/mfa/disable

Authorizations

Body

otpstring

backupCodestring

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/mfa/disable' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json'

200

400

500

200

No body

ok

Regenarete backup codes a user

post

/mfa/regenerate/backupcodes

Authorizations

Body

otpstring

backupCodestring

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/mfa/regenerate/backupcodes' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json'

200

400

500

200

{
  "backupCodes": [
    "text"
  ]
}

ok

Checks if a user is enrolled to mfa or not

get

/mfa/isenrolled

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/mfa/isenrolled' \
  --header 'Authorization: YOUR_API_KEY'

200

400

500

200

{
  "isEnrolled": true
}

ok