API Definition

81KB

Auth-Server Schema.yaml

LDAP configuration

GET/api/auth/ldap

Authorization

ApiKeyHeader

Response

200

LDAP configuration

Body

application/json

enabled*boolean

modestring

Request

JavaScriptCurlPython

const response = await fetch('/api/auth/ldap', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

MFA configuration

GET/api/auth/mfa

Authorization

ApiKeyHeader

Response

200

MFA configuration

Body

application/json

enabled*boolean

Request

JavaScriptCurlPython

const response = await fetch('/api/auth/mfa', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "enabled": false
}

Create a new user

POST/api/users

Authorization

ApiKeyHeader

Body

application/json

User to be created

username*string

autoGeneratedboolean

mqttPublishPrefixstring

passwordstring

identityProvider*IdentityProvider (enum)

localldap

grantTypes*array of GrantType (object)

certificatesarray of Certificate (object)

initialPermissionsarray of Permission (object)

rolesarray of string

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

enforceMFAEnrollmentboolean

Response

201400

Created

Body

application/json

idstring

usernamestring

autoGeneratedboolean

mqttPublishPrefixstring

identityProviderIdentityProvider (enum)

localldap

grantTypesarray of GrantType (object)

tokensarray of Token (object)

certificatesarray of Certificate (object)

rolesarray of Role (object)

mfa_is_enrolledboolean

enforceMFAEnrollmentboolean

Request

JavaScriptCurlPython

const response = await fetch('/api/users', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "username": "text",
      "identityProvider": "local",
      "grantTypes": [
        {}
      ]
    }),
});
const data = await response.json();

Response

201

{
  "id": "text",
  "username": "text",
  "autoGenerated": false,
  "mqttPublishPrefix": "text",
  "identityProvider": "local",
  "grantTypes": [
    {
      "method": "password",
      "isRequired": false
    }
  ],
  "tokens": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text",
      "label": "text"
    }
  ],
  "certificates": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text"
    }
  ],
  "roles": [
    {
      "id": "text",
      "name": "text",
      "isShared": false,
      "permissions": [
        {
          "id": "text",
          "resource": "text",
          "operation": "read",
          "context": "http"
        }
      ]
    }
  ],
  "mfa_is_enrolled": false,
  "enforceMFAEnrollment": false
}

List users

GET/api/listUsers

Authorization

ApiKeyHeader

Query parameters

Response

200400

Object with array of users and pagination information

Body

application/json

usersarray of User (object)

paginationPagination (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/listUsers', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "users": [
    {
      "id": "text",
      "username": "text",
      "autoGenerated": false,
      "mqttPublishPrefix": "text",
      "identityProvider": "local",
      "grantTypes": [
        {
          "method": "password",
          "isRequired": false
        }
      ],
      "tokens": [
        {
          "fingerprint": "text",
          "createdAt": "text",
          "expiresAt": "text",
          "label": "text"
        }
      ],
      "certificates": [
        {
          "fingerprint": "text",
          "createdAt": "text",
          "expiresAt": "text"
        }
      ],
      "roles": [
        {
          "id": "text",
          "name": "text",
          "isShared": false,
          "permissions": [
            {
              "id": "text",
              "resource": "text",
              "operation": "read",
              "context": "http"
            }
          ]
        }
      ],
      "mfa_is_enrolled": false,
      "enforceMFAEnrollment": false
    }
  ],
  "pagination": {}
}

List all usernames

GET/api/users/usernames

Authorization

ApiKeyHeader

Response

200

Array of user ids

Body

application/json

usernamestring

idstring

Request

JavaScriptCurlPython

const response = await fetch('/api/users/usernames', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

List user ids

GET/api/users/ids

Authorization

ApiKeyHeader

Response

200

Array of user ids

Body

application/json

itemsstring

Request

JavaScriptCurlPython

const response = await fetch('/api/users/ids', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  "text"
]

Create new users in batch

POST/api/users/batch

Authorization

ApiKeyHeader

Body

application/json

User to be created

username*string

autoGeneratedboolean

mqttPublishPrefixstring

passwordstring

identityProvider*IdentityProvider (enum)

localldap

grantTypes*array of GrantType (object)

certificatesarray of Certificate (object)

initialPermissionsarray of Permission (object)

rolesarray of string

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

enforceMFAEnrollmentboolean

Response

201400

Created

Body

application/json

itemsstring

Request

JavaScriptCurlPython

const response = await fetch('/api/users/batch', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {
        "username": "text",
        "identityProvider": "local",
        "grantTypes": [
          {}
        ]
      }
    ]),
});
const data = await response.json();

Response

201

[
  "text"
]

Delete users in batch

POST/api/users/batch/delete

Authorization

ApiKeyHeader

Body

application/json

User IDs to be deleted

itemsstring

Response

200400

ok

Request

JavaScriptCurlPython

const response = await fetch('/api/users/batch/delete', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      "text"
    ]),
});
const data = await response.json();

Change user password

PUT/api/users/change-password

Authorization

ApiKeyHeader

Body

application/json

Credentials

passwordstring

newPasswordstring

Response

204400

Changed

Request

JavaScriptCurlPython

const response = await fetch('/api/users/change-password', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Get a specific user

GET/api/users/{id}

Authorization

ApiKeyHeader

Path parameters

id*string

Id of user

Response

200404

User

Body

application/json

idstring

usernamestring

autoGeneratedboolean

mqttPublishPrefixstring

identityProviderIdentityProvider (enum)

localldap

grantTypesarray of GrantType (object)

tokensarray of Token (object)

certificatesarray of Certificate (object)

rolesarray of Role (object)

mfa_is_enrolledboolean

enforceMFAEnrollmentboolean

Request

JavaScriptCurlPython

const response = await fetch('/api/users/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "id": "text",
  "username": "text",
  "autoGenerated": false,
  "mqttPublishPrefix": "text",
  "identityProvider": "local",
  "grantTypes": [
    {
      "method": "password",
      "isRequired": false
    }
  ],
  "tokens": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text",
      "label": "text"
    }
  ],
  "certificates": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text"
    }
  ],
  "roles": [
    {
      "id": "text",
      "name": "text",
      "isShared": false,
      "permissions": [
        {
          "id": "text",
          "resource": "text",
          "operation": "read",
          "context": "http"
        }
      ]
    }
  ],
  "mfa_is_enrolled": false,
  "enforceMFAEnrollment": false
}

Update an existing user

PUT/api/users/{id}

Authorization

ApiKeyHeader

Path parameters

id*string

Id of user

Body

application/json

Data required for update of a user

usernamestring

passwordstring

mqttPublishPrefixstring

identityProviderIdentityProvider (enum)

localldap

grantTypesarray of GrantType (object)

rolesarray of string

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

permissionsarray of Permission (object)

disableMfaboolean

Indicates that MFA for the given user should be disabled

enforceMFAEnrollmentboolean

Enforces the user to enroll MFA

Response

200400404

OK

Body

application/json

idstring

usernamestring

autoGeneratedboolean

mqttPublishPrefixstring

identityProviderIdentityProvider (enum)

localldap

grantTypesarray of GrantType (object)

tokensarray of Token (object)

certificatesarray of Certificate (object)

rolesarray of Role (object)

mfa_is_enrolledboolean

enforceMFAEnrollmentboolean

Request

JavaScriptCurlPython

const response = await fetch('/api/users/{id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "id": "text",
  "username": "text",
  "autoGenerated": false,
  "mqttPublishPrefix": "text",
  "identityProvider": "local",
  "grantTypes": [
    {
      "method": "password",
      "isRequired": false
    }
  ],
  "tokens": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text",
      "label": "text"
    }
  ],
  "certificates": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text"
    }
  ],
  "roles": [
    {
      "id": "text",
      "name": "text",
      "isShared": false,
      "permissions": [
        {
          "id": "text",
          "resource": "text",
          "operation": "read",
          "context": "http"
        }
      ]
    }
  ],
  "mfa_is_enrolled": false,
  "enforceMFAEnrollment": false
}

Delete an existing user

DELETE/api/users/{id}

Authorization

ApiKeyHeader

Path parameters

id*string

Id of user

Response

200404409

OK

Request

JavaScriptCurlPython

const response = await fetch('/api/users/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Get all tokens generated by this user

GET/api/users/{id}/tokens

Authorization

ApiKeyHeader

Path parameters

id*string

Id of user

Response

200404

List of user generated tokens

Body

application/json

fingerprintstring

createdAtstring

expiresAtstring

labelstring

Request

JavaScriptCurlPython

const response = await fetch('/api/users/{id}/tokens', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

Delete all tokens generated by this user

DELETE/api/users/{id}/tokens

Authorization

ApiKeyHeader

Path parameters

id*string

Id of user

Query parameters

Response

200404

Token(s) deleted

Request

JavaScriptCurlPython

const response = await fetch('/api/users/{id}/tokens', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Add a new certificate to a user

POST/api/users/{id}/certificates

Authorization

ApiKeyHeader

Path parameters

id*string

Id of user

Body

application/json

Certificate to be created

fingerprint*string

Response

201400

Created

Request

JavaScriptCurlPython

const response = await fetch('/api/users/{id}/certificates', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "fingerprint": "text"
    }),
});
const data = await response.json();

Delete an existing certificate

DELETE/api/users/{id}/certificates

Authorization

ApiKeyHeader

Path parameters

id*string

Id of user

Body

application/json

Data required for deleting a certificate

fingerprint*string

Response

200400404

OK

Request

JavaScriptCurlPython

const response = await fetch('/api/users/{id}/certificates', {
    method: 'DELETE',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "fingerprint": "text"
    }),
});
const data = await response.json();

Add a new role to a user

POST/api/users/{id}/roles

Authorization

ApiKeyHeader

Path parameters

id*string

Id of user

Body

application/json

Role to be added

roleId*string

Response

201400404

Created

Request

JavaScriptCurlPython

const response = await fetch('/api/users/{id}/roles', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "roleId": "text"
    }),
});
const data = await response.json();

Remove a role from a user

DELETE/api/users/{id}/roles

Authorization

ApiKeyHeader

Path parameters

id*string

Id of user

Body

application/json

Data required for deleting a role

roleId*string

Response

200400404409

OK

Request

JavaScriptCurlPython

const response = await fetch('/api/users/{id}/roles', {
    method: 'DELETE',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "roleId": "text"
    }),
});
const data = await response.json();

Create a new role

POST/api/roles

Authorization

ApiKeyHeader

Body

application/json

Role to be created

name*string

isShared*boolean

autoGeneratedboolean

permissionsarray of Permission (object)

Response

201400

Created

Body

application/json

idstring

namestring

isSharedboolean

permissionsarray of Permission (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/roles', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text",
      "isShared": false
    }),
});
const data = await response.json();

Response

201

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

List roles

GET/api/roles

Authorization

ApiKeyHeader

Query parameters

Response

200401403

Array of roles

Body

application/json

idstring

namestring

isSharedboolean

permissionsarray of Permission (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/roles', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

List paginated roles

GET/api/roles/page

Authorization

ApiKeyHeader

Query parameters

Response

200400401403

Object with array of roles and pagination information

Body

application/json

rolesarray of PaginatedRole (object)

paginationPagination (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/roles/page', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "roles": [
    {
      "id": "text",
      "name": "text",
      "isshared": false,
      "autogenerated": false,
      "users": [
        {}
      ],
      "permissions": [
        {}
      ]
    }
  ],
  "pagination": {}
}

List roles names

GET/api/roles/names

Authorization

ApiKeyHeader

Response

200401403

Object with array of roles names and ids

Body

application/json

idstring

namestring

Request

JavaScriptCurlPython

const response = await fetch('/api/roles/names', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

Get a specific role

GET/api/roles/{id}

Authorization

ApiKeyHeader

Path parameters

id*string

Id of role

Response

200401403404

Role

Body

application/json

idstring

namestring

isSharedboolean

permissionsarray of Permission (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/roles/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

Update an existing role

PUT/api/roles/{id}

Authorization

ApiKeyHeader

Path parameters

id*string

Id of role

Body

application/json

Data required for update of a role

name*string

isSharedboolean

permissionsarray of Permission (object)

Response

200400404

OK

Body

application/json

idstring

namestring

isSharedboolean

permissionsarray of Permission (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/roles/{id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text"
    }),
});
const data = await response.json();

Response

200

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

Delete an existing role

DELETE/api/roles/{id}

Authorization

ApiKeyHeader

Path parameters

id*string

Id of role

Response

200400404409

OK

Request

JavaScriptCurlPython

const response = await fetch('/api/roles/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

List role permissions

GET/api/roles/{id}/permissions

Authorization

ApiKeyHeader

Path parameters

id*string

Id of role

Response

200401403404

Array of permissions

Body

application/json

idstring

resourcestring

The MQTT topic or REST URL path for which the permission is granted. Both may include MQTT-style wildcards.

operationOperation (enum)

readwritereadWrite

contextContext (enum)

httpmqtt

Request

JavaScriptCurlPython

const response = await fetch('/api/roles/{id}/permissions', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

Add a new permission to a role

POST/api/roles/{id}/permissions

Authorization

ApiKeyHeader

Path parameters

id*string

Id of role

Body

application/json

Permission to be created

resource*string

operation*Operation (enum)

readwritereadWrite

context*Context (enum)

httpmqtt

Response

201400409

Created

Request

JavaScriptCurlPython

const response = await fetch('/api/roles/{id}/permissions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "resource": "text",
      "operation": "read",
      "context": "http"
    }),
});
const data = await response.json();

Update an existing permission

GET/api/roles/{id}/permissions/{pemId}

Authorization

ApiKeyHeader

Path parameters

id*string

Id of role

pemId*string

Id of permission

Response

200400404

Permission

Body

application/json

idstring

resourcestring

The MQTT topic or REST URL path for which the permission is granted. Both may include MQTT-style wildcards.

operationOperation (enum)

readwritereadWrite

contextContext (enum)

httpmqtt

Request

JavaScriptCurlPython

const response = await fetch('/api/roles/{id}/permissions/{pemId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

Update an existing permission

PUT/api/roles/{id}/permissions/{pemId}

Authorization

ApiKeyHeader

Path parameters

id*string

Id of role

pemId*string

Id of permission

Body

application/json

Data required for update of a permission

resourcestring

operation*Operation (enum)

readwritereadWrite

Response

200400404

OK

Request

JavaScriptCurlPython

const response = await fetch('/api/roles/{id}/permissions/{pemId}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "operation": "read"
    }),
});
const data = await response.json();

Delete an existing permission

DELETE/api/roles/{id}/permissions/{pemId}

Authorization

ApiKeyHeader

Path parameters

id*string

Id of role

pemId*string

Id of permission

Response

200400404

OK

Request

JavaScriptCurlPython

const response = await fetch('/api/roles/{id}/permissions/{pemId}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Login into the cybus connectware

POST/api/login

Body

application/json

Authentication credentials

username*string

password*string

expireTimeInHoursnumber

labelstring

Response

200400403

OK

Body

application/json

tokenstring

expiresAtstring

permissionsarray of Permission (object)

Permissions the authenticated user has

needsMfaboolean

Present when MFA was enrolled by the user already

secretstring

enforceMFAEnrollmentboolean

Present when MFA has to be enrolled but was not enrolled by the user

Request

JavaScriptCurlPython

const response = await fetch('/api/login', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "username": "text",
      "password": "text"
    }),
});
const data = await response.json();

Response

200

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

Return the session of the current user

GET/api/session

Authorization

ApiKeyHeader

Response

200401

OK

Body

application/json

usernamestring

expiresAtstring

permissionsarray of Permission (object)

Permissions the authenticated user has

mfaobject

Request

JavaScriptCurlPython

const response = await fetch('/api/session', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "username": "text",
  "expiresAt": "text",
  "permissions": [
    {
      "id": "text",
      "resource": "text",
      "operation": "read",
      "context": "http"
    }
  ],
  "mfa": {
    "enabled": false,
    "enforced": false
  }
}

Return the permissions of the current user

GET/api/permissions

Authorization

ApiKeyHeader

Response

200401

OK

Request

JavaScriptCurlPython

const response = await fetch('/api/permissions', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Return a page of all permissions

GET/api/permissions/page

Authorization

ApiKeyHeader

Query parameters

Response

200400401

Object with array of permissions and pagination information

Body

application/json

permissionsarray of PermissionWithUsage (object)

paginationPagination (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/permissions/page', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "permissions": [
    {
      "resource": "text",
      "context": "http",
      "usage": [
        {
          "roleName": "text",
          "roleId": "text",
          "isRoleShared": "text",
          "operation": "read"
        }
      ]
    }
  ],
  "pagination": {}
}

Return all permissions ids

GET/api/permissions/ids

Authorization

ApiKeyHeader

Response

200401

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

Body

application/json

resourcestring

The permission's resource

operationOperation (enum)

readwritereadWrite

contextContext (enum)

httpmqtt

idsarray of string

The ids that have the same aformentioned resource, operation and context

Request

JavaScriptCurlPython

const response = await fetch('/api/permissions/ids', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

Logout of the cybus connectware

POST/api/logout

Body

application/json

Token data

token*string

Response

200400404

OK

Request

JavaScriptCurlPython

const response = await fetch('/api/logout', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "token": "text"
    }),
});
const data = await response.json();

Endpoint for self-registration of clients

POST/api/client-registry/register

Body

application/json

username*string

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

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\nQWtHQTFVRUJoTUNSRVV4RHpBTkJnTlZCQWdNQmtKbGNteHBiakVVTUJJRwpBMVVFQ2d3TFVtOWli\nM1J6SUVsdVl5NHhEREFLQmdOVkJBc01BMUltUkRFTk1Bc0dBMVVFQXd3RVVqSkVNakVjCk1Cb0dD\nU3FHU0liM0RRRUpBUllOY2pKa01rQmplV0oxY3k1cGJ6Q0NBU0l3RFFZSktvWklodmNOQVFFQkJR\nQUQKZ2dFUEFEQ0NBUW9DZ2dFQkFNSXlsQmk4azFIZDJseERXZHd5N1Z3WngvaUlrdWpTUUVtWmdk\nY0JqNk4veTZTSQpiTGMwdFpmK2JGWUZZZ2p0OHRFUUJPRzhNeW94YmYwQSs4T0dHZFJvV3l2eHFt\nci9TLzhNa1ZGUXJiS2duMDBaCmVrdWlZQVBUOFMvT0FZVnlGT21rWWtWSm0wdkRwMmRkcXRiTUZY\nbXZ1OGxnVnVPckFwMEQ4TjdBcVgwWlUwc0UKZzRmVkdpREtnS040cUFEcXR3aVZKb0dsR0JCYWpm\nejAxSlhEWnhpUEVac3BYSGJyaVY0Z1JvV0VIVGNGcWc4cgo1WCtZRDlqTGVGdFdRb0g5SHA3ZEFP\nY1lCRktVRVZjWTlGN20vRWZkVFBwNjNnbTdRdFR4S0EvelIyODRWQUVCCjZFbC8xU2FCME54YlVw\nbHgzVHp4T2ZKYjJpdEd0S1RzN1U2UnF3VUNBd0VBQWFBQU1BMEdDU3FHU0liM0RRRUIKQ3dVQUE0\nSUJBUUIxejdKcGRIRERScTl2WE1BMmNBVVZBRmYvYkRXNzlkNmlMQ0pDVDZ5WlhOcHV0ZXA3N1pQ\ndQpIMSszb08vZmRJdDhaOThjV0J4ZVBNckVDM2krQ0lIdms4a202SVFMVW05cUZVdHRDN0VjUmpU\nUFYwT29vb2l0ClhXOHhzWVhGaEZPTStydTJnbEcrSUVMY3BydS9JamxyVHpwaUtNZVJGQ1FFemww\nWWtZRDZkSk82ME1CRVhjZUgKWHpFZTRtT2oxUDJKNFcycFI1bDFsQjZ5dXB4SWVuRjRhNm5EeFFE\neFZkcmtBTHNJdDhGZUNTNDNvaHg4NVQ5SApHN2IwOFdmdEFrYzhKR3ZLb00rdE90MzlVZFFESE1S\nOU5QOG9RUUpMaldMcWZRdUtaRmZXNVJyR24zSzA2UGNICkRMN1FNc1hxNFBaMyswUXpCSjZJVGoz\naUZubHp1VXBqCi0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo=\n"

rolesarray of string

Name of roles the user wants to be assigned to

permissionsarray of Permission (object)

Permissions the user wants to be granted individually

context*string

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

Example: "IoT Device Serial Number <0123456>"

Response

201202400409422423

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

Body

application/json

certificatestring

Signed certificate in Base64 encoded PEM format. This is only supplied if a CSR had been present in the registration payload.

Example: "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"

Request

JavaScriptCurlPython

const response = await fetch('/api/client-registry/register', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "context": "IoT Device Serial Number <0123456>",
      "username": "iot.device.0123456"
    }),
});
const data = await response.json();

Response

201422

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

Receive a list of all pending registration requests

GET/api/client-registry

Authorization

ApiKeyHeader

Response

200401

OK

Body

application/json

timestampstring

String with ISO 8601 timestamp of the last request update.

Example: "2022-03-25T17:25:21.379Z"

usernamestring

Username that is requested to be granted access.

Example: "iot.device.0123456"

credentialTypeenum

certificatepassword

rolesarray of string

contextstring

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

Example: "IoT Device Serial Number <0123456>"

permissionsPermission (object)

grantedboolean

Request

JavaScriptCurlPython

const response = await fetch('/api/client-registry', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "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": false
  }
]

Return the current lock status of the registration endpoint

GET/api/client-registry/status

Authorization

ApiKeyHeader

Response

200

OK

Body

application/json

status*enum

openlocked

unlockedUntilnumber

Request

JavaScriptCurlPython

const response = await fetch('/api/client-registry/status', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

Open the registration endpoint temporarily

POST/api/client-registry/open

Authorization

ApiKeyHeader

Body

application/json

durationinteger

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

Example: 30000

Response

204401

OK

Request

JavaScriptCurlPython

const response = await fetch('/api/client-registry/open', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

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

POST/api/client-registry/lock

Authorization

ApiKeyHeader

Response

204401

OK

Request

JavaScriptCurlPython

const response = await fetch('/api/client-registry/lock', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Confirm a single authentication request

POST/api/client-registry/confirm

Authorization

ApiKeyHeader

Body

application/json

username*string

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

mqttPublishPrefixstring

grantTypesarray of GrantType (object)

initialPermissionsarray of Permission (object)

rolesarray of string

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

Response

204401404

OK

Body

application/json

idstring

usernamestring

autoGeneratedboolean

mqttPublishPrefixstring

identityProviderIdentityProvider (enum)

localldap

grantTypesarray of GrantType (object)

tokensarray of Token (object)

certificatesarray of Certificate (object)

rolesarray of Role (object)

mfa_is_enrolledboolean

enforceMFAEnrollmentboolean

Request

JavaScriptCurlPython

const response = await fetch('/api/client-registry/confirm', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "username": "text"
    }),
});
const data = await response.json();

Response

204

{
  "id": "text",
  "username": "text",
  "autoGenerated": false,
  "mqttPublishPrefix": "text",
  "identityProvider": "local",
  "grantTypes": [
    {
      "method": "password",
      "isRequired": false
    }
  ],
  "tokens": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text",
      "label": "text"
    }
  ],
  "certificates": [
    {
      "fingerprint": "text",
      "createdAt": "text",
      "expiresAt": "text"
    }
  ],
  "roles": [
    {
      "id": "text",
      "name": "text",
      "isShared": false,
      "permissions": [
        {
          "id": "text",
          "resource": "text",
          "operation": "read",
          "context": "http"
        }
      ]
    }
  ],
  "mfa_is_enrolled": false,
  "enforceMFAEnrollment": false
}

List certificates

GET/api/certificates

Authorization

ApiKeyHeader

Response

200500

Array of certficates

Body

application/json

idstring

issuedByobject

issuedToobject

keyUsagearray of string

extendedKeyUsagearray of string

basicConstraintsobject

issuedOnnumber

expiresOnnumber

fingerprintsobject

removableboolean

Request

JavaScriptCurlPython

const response = await fetch('/api/certificates', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

Deletes certificate

DELETE/api/certificates

Authorization

ApiKeyHeader

Query parameters

Response

200400404500

OK

Request

JavaScriptCurlPython

const response = await fetch('/api/certificates?id=text', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Add certificate

POST/api/certificates

Authorization

ApiKeyHeader

Body

application/json

Certificate content to be added, a chain can be passed and will be accepted

string

Response

201400

Array of added certficates

Body

application/json

idstring

issuedByobject

issuedToobject

keyUsagearray of string

extendedKeyUsagearray of string

basicConstraintsobject

issuedOnnumber

expiresOnnumber

fingerprintsobject

removableboolean

Request

JavaScriptCurlPython

const response = await fetch('/api/certificates', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify("text"),
});
const data = await response.json();

Response

201

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

Returns given certificate content

GET/api/certificates/content

Authorization

ApiKeyHeader

Query parameters

Response

200400404500

Certificate content

Body

application/json

string

Request

JavaScriptCurlPython

const response = await fetch('/api/certificates/content?id=text', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

text

Enhanced authentication of MQTT5 (not supported)

POST/api/broker/auth/enhanced

Body

application/json

Not supported

client_idstring

propertiesobject

Response

200

OK

Body

application/json

resultstring

modifiersobject

Request

JavaScriptCurlPython

const response = await fetch('/api/broker/auth/enhanced', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

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

Return a password policy rules

GET/api/policy/password

Authorization

ApiKeyHeader

Response

200

OK

Body

application/json

mininteger

The minimum number of characters a password must contain. Zero disables this rule.

lowerinteger

The minimum number of lower-case letters a password must contain. Zero disables this rule.

upperinteger

The minimum number of upper-case letters a password must contain. Zero disables this rule.

numericinteger

The minimum number of digit numbers a password must contain. Zero disables this rule.

symbolinteger

The minimum number of symbol or punctuation characters a password must contain. Zero disables this rule.

Request

JavaScriptCurlPython

const response = await fetch('/api/policy/password', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{}

Return a database maintenance status

GET/api/maintenance/db

Authorization

ApiKeyHeader

Response

200

OK

Body

application/json

runningboolean

Indicate the current running status of a backup/restore operation.

backupMaintenanceDbStatus (object)

restoreMaintenanceDbStatus (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/maintenance/db', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "running": false,
  "backup": {
    "id": "text",
    "succeeded": false,
    "statusMessage": "text",
    "startDate": "2024-11-21T21:00:19.083Z",
    "endDate": "2024-11-21T21:00:19.083Z"
  },
  "restore": {
    "id": "text",
    "succeeded": false,
    "statusMessage": "text",
    "startDate": "2024-11-21T21:00:19.083Z",
    "endDate": "2024-11-21T21:00:19.083Z"
  }
}

Download a database backup

GET/api/maintenance/db/backup

Authorization

ApiKeyHeader

Response

200423

OK

Body

application/gzip

string

Request

JavaScriptCurlPython

const response = await fetch('/api/maintenance/db/backup', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

text

Start a database backup

POST/api/maintenance/db/backup

Authorization

ApiKeyHeader

Response

202423

Accepted. Database backup started.

Body

multipart/form-data

string (binary)

Request

JavaScriptCurlPython

const response = await fetch('/api/maintenance/db/backup', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

202

binary

Upload archive and start database restore

POST/api/maintenance/db/restore

Authorization

ApiKeyHeader

Response

202423

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

Request

JavaScriptCurlPython

const response = await fetch('/api/maintenance/db/restore', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Enable MFA for an existing user

POST/api/mfa/enable

Authorization

ApiKeyHeader

Response

200400409500

ok

Body

application/json

uri*string

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

Request

JavaScriptCurlPython

const response = await fetch('/api/mfa/enable', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

200

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

Validate MFA enrollment of the user

POST/api/mfa/validate

Authorization

ApiKeyHeader

Body

application/json

User to validate

otp*string

Response

200400401500

ok

Body

application/json

backupCodes*array of string

Request

JavaScriptCurlPython

const response = await fetch('/api/mfa/validate', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "otp": "text"
    }),
});
const data = await response.json();

Response

200

{
  "backupCodes": [
    "text"
  ]
}

Login user with MFA

POST/api/mfa/login

Authorization

ApiKeyHeader

Body

application/json

All necessary data for logging in with MFA

username*string

otpstring

backupCodestring

secret*string

Response

200400401403500

ok

Body

application/json

tokenstring

expiresAtstring

permissionsarray of Permission (object)

Permissions the authenticated user has

needsMfaboolean

Present when MFA was enrolled by the user already

secretstring

enforceMFAEnrollmentboolean

Present when MFA has to be enrolled but was not enrolled by the user

Request

JavaScriptCurlPython

const response = await fetch('/api/mfa/login', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "username": "text",
      "secret": "text"
    }),
});
const data = await response.json();

Response

200401403

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

User self de-registration from MFA

POST/api/mfa/disable

Authorization

ApiKeyHeader

Body

application/json

User to disable

otpstring

backupCodestring

Response

200400500

ok

Request

JavaScriptCurlPython

const response = await fetch('/api/mfa/disable', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Regenarete backup codes a user

POST/api/mfa/regenerate/backupcodes

Authorization

ApiKeyHeader

Body

application/json

User to regenerate codes for

otpstring

backupCodestring

Response

200400500

ok

Body

application/json

backupCodes*array of string

Request

JavaScriptCurlPython

const response = await fetch('/api/mfa/regenerate/backupcodes', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "backupCodes": [
    "text"
  ]
}

Checks if a user is enrolled to mfa or not

GET/api/mfa/isenrolled

Authorization

ApiKeyHeader

Response

200400500

ok

Body

application/json

isEnrolled*boolean

Request

JavaScriptCurlPython

const response = await fetch('/api/mfa/isenrolled', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "isEnrolled": false
}