API Definition

81KB

Auth-Server Schema.yaml

LDAP configuration

get

Authorizations

Responses

200

LDAP configuration

application/json

get

HTTPcURLJavaScriptPython

GET /api/auth/ldap HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

200

LDAP configuration

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

MFA configuration

get

Authorizations

Responses

200

MFA configuration

application/json

get

HTTPcURLJavaScriptPython

GET /api/auth/mfa HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

200

MFA configuration

{
  "enabled": false
}

Create a new user

post

Authorizations

Body

usernamestring · min: 3Required

autoGeneratedbooleanOptionalDefault: false

mqttPublishPrefixstringOptional

passwordstring · min: 5Optional

identityProviderstring · enumRequiredPossible values:

rolesstring[]Optional

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

enforceMFAEnrollmentbooleanOptionalDefault: false

Responses

201

Created

application/json

400

Invalid request

post

HTTPcURLJavaScriptPython

POST /api/users HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 383

{
  "username": "text",
  "autoGenerated": false,
  "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": false
}

{
  "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"
        }
      ]
    }
  ],
  "mfa_is_enrolled": true,
  "enforceMFAEnrollment": true
}

List users

get

Authorizations

Query parameters

username[eq]string[]Optional

The optional list to be matched against the usernames

pageNumberintegerOptional

The page number to fetch, starts at page 1

rowsPerPageinteger · max: 100Optional

The number of records per page to return

excludeAutoGeneratedbooleanOptional

If the auto generated roles should be excluded from the results

Responses

200

Object with array of users and pagination information

application/json

400

Bad Request

application/json

get

HTTPcURLJavaScriptPython

GET /api/listUsers HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

{
  "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"
            }
          ]
        }
      ],
      "mfa_is_enrolled": true,
      "enforceMFAEnrollment": true
    }
  ],
  "pagination": {
    "totalPages": 1,
    "totalRows": 1,
    "totalRowsInPage": 1,
    "currentPage": 1,
    "nextPage": 1,
    "rowsPerPage": 1
  }
}

List all usernames

get

Authorizations

Responses

200

Array of user ids

application/json

get

HTTPcURLJavaScriptPython

GET /api/users/usernames HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

200

Array of user ids

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

List user ids

get

Authorizations

Responses

200

Array of user ids

application/json

Responsestring[]

get

HTTPcURLJavaScriptPython

GET /api/users/ids HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

200

Array of user ids

[
  "text"
]

Create new users in batch

post

Authorizations

Body

usernamestring · min: 3Required

autoGeneratedbooleanOptionalDefault: false

mqttPublishPrefixstringOptional

passwordstring · min: 5Optional

identityProviderstring · enumRequiredPossible values:

rolesstring[]Optional

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

enforceMFAEnrollmentbooleanOptionalDefault: false

Responses

201

Created

application/json

Responsestring[]

400

Invalid request

post

HTTPcURLJavaScriptPython

POST /api/users/batch HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 385

[
  {
    "username": "text",
    "autoGenerated": false,
    "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": false
  }
]

[
  "text"
]

Delete users in batch

post

Authorizations

Body

string[]Optional

Responses

200

ok

400

Invalid request

post

HTTPcURLJavaScriptPython

POST /api/users/batch/delete HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 8

[
  "text"
]

No content

Change user password

put

Authorizations

Body

passwordstringOptional

newPasswordstring · min: 5Optional

Responses

204

Changed

400

Invalid request

put

HTTPcURLJavaScriptPython

PUT /api/users/change-password HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 40

{
  "password": "text",
  "newPassword": "text"
}

No content

Get a specific user

get

Authorizations

Path parameters

idstringRequired

Id of user

Responses

200

User

application/json

404

User not found

get

HTTPcURLJavaScriptPython

GET /api/users/{id} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

{
  "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"
        }
      ]
    }
  ],
  "mfa_is_enrolled": true,
  "enforceMFAEnrollment": true
}

Update an existing user

put

Authorizations

Path parameters

idstringRequired

Id of user

Body

usernamestring · min: 3Optional

passwordstringOptional

mqttPublishPrefixstringOptional

identityProviderstring · enumOptionalPossible values:

rolesstring[]Optional

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

disableMfabooleanOptional

Indicates that MFA for the given user should be disabled

enforceMFAEnrollmentbooleanOptional

Enforces the user to enroll MFA

Responses

200

OK

application/json

400

Invalid request

404

User not found

put

HTTPcURLJavaScriptPython

PUT /api/users/{id} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 293

{
  "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"
        }
      ]
    }
  ],
  "mfa_is_enrolled": true,
  "enforceMFAEnrollment": true
}

Delete an existing user

delete

Authorizations

Path parameters

idstringRequired

Id of user

Responses

200

OK

404

User not found

409

Invalid argument error

delete

HTTPcURLJavaScriptPython

DELETE /api/users/{id} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

No content

Get all tokens generated by this user

get

Authorizations

Path parameters

idstringRequired

Id of user

Responses

200

List of user generated tokens

application/json

404

User not found

get

HTTPcURLJavaScriptPython

GET /api/users/{id}/tokens HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

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

Delete all tokens generated by this user

delete

Authorizations

Path parameters

idstringRequired

Id of user

Query parameters

tokenIdstringOptional

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

Responses

200

Token(s) deleted

404

Error ocurred when attempting to delete token(s)

delete

HTTPcURLJavaScriptPython

DELETE /api/users/{id}/tokens HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

No content

Add a new certificate to a user

post

Authorizations

Path parameters

idstringRequired

Id of user

Body

fingerprintstringRequired

Responses

201

Created

400

Invalid request

post

HTTPcURLJavaScriptPython

POST /api/users/{id}/certificates HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "fingerprint": "text"
}

No content

Delete an existing certificate

delete

Authorizations

Path parameters

idstringRequired

Id of user

Body

fingerprintstringRequired

Responses

200

OK

400

Invalid request

404

Certificate not found

delete

HTTPcURLJavaScriptPython

DELETE /api/users/{id}/certificates HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "fingerprint": "text"
}

No content

Add a new role to a user

post

Authorizations

Path parameters

idstringRequired

Id of user

Body

roleIdstringRequired

Responses

201

Created

400

Invalid request

404

User or role not found

post

HTTPcURLJavaScriptPython

POST /api/users/{id}/roles HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "roleId": "text"
}

No content

Remove a role from a user

delete

Authorizations

Path parameters

idstringRequired

Id of user

Body

roleIdstringRequired

Responses

200

OK

400

Invalid request

404

User or role not found

409

Invalid argument error

delete

HTTPcURLJavaScriptPython

DELETE /api/users/{id}/roles HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "roleId": "text"
}

No content

Create a new role

post

Authorizations

Body

namestringRequired

isSharedbooleanRequired

autoGeneratedbooleanOptional

Responses

201

Created

application/json

400

Invalid request

post

HTTPcURLJavaScriptPython

POST /api/roles HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 136

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

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

List roles

get

Authorizations

Query parameters

name[eq]stringOptional

Filter by equal to name

Responses

200

Array of roles

application/json

401

Authentication Error

403

Authorization Error

get

HTTPcURLJavaScriptPython

GET /api/roles HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

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

List paginated roles

get

Authorizations

Query parameters

namesstring[]Optional

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

autoGeneratedbooleanOptional

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

isSharedbooleanOptional

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

Responses

200

Object with array of roles and pagination information

application/json

400

Invalid args provided

401

Authentication Error

403

Authorization Error

get

HTTPcURLJavaScriptPython

GET /api/roles/page?rowsPerPage=1&pageNumber=1 HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

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

List roles names

get

Authorizations

Responses

200

Object with array of roles names and ids

application/json

401

Authentication Error

403

Authorization Error

get

HTTPcURLJavaScriptPython

GET /api/roles/names HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

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

Get a specific role

get

Authorizations

Path parameters

idstringRequired

Id of role

Responses

200

Role

application/json

401

Authentication Error

403

Authorization Error

404

Role not found

get

HTTPcURLJavaScriptPython

GET /api/roles/{id} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

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

Update an existing role

put

Authorizations

Path parameters

idstringRequired

Id of role

Body

namestringRequired

isSharedbooleanOptional

Responses

200

OK

application/json

400

Invalid request

404

Role not found

put

HTTPcURLJavaScriptPython

PUT /api/roles/{id} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 115

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

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

Delete an existing role

delete

Authorizations

Path parameters

idstringRequired

Id of role

Responses

200

OK

400

Invalid request

404

Role not found

409

Invalid argument error

delete

HTTPcURLJavaScriptPython

DELETE /api/roles/{id} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

No content

List role permissions

get

Authorizations

Path parameters

idstringRequired

Id of role

Responses

200

Array of permissions

application/json

401

Authentication Error

403

Authorization Error

404

Role not found

get

HTTPcURLJavaScriptPython

GET /api/roles/{id}/permissions HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

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

Add a new permission to a role

post

Authorizations

Path parameters

idstringRequired

Id of role

Body

resourcestringRequired

operationstring · enumRequiredPossible values:

contextstring · enumRequiredPossible values:

Responses

201

Created

400

Invalid request

409

Conflict - permission already declared

post

HTTPcURLJavaScriptPython

POST /api/roles/{id}/permissions HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 55

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

No content

Update an existing permission

get

Authorizations

Path parameters

idstringRequired

Id of role

pemIdstringRequired

Id of permission

Responses

200

Permission

application/json

400

Invalid request

404

User not found

get

HTTPcURLJavaScriptPython

GET /api/roles/{id}/permissions/{pemId} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

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

Update an existing permission

put

Authorizations

Path parameters

idstringRequired

Id of role

pemIdstringRequired

Id of permission

Body

resourcestringOptional

operationstring · enumRequiredPossible values:

Responses

200

OK

400

Invalid request

404

Permission not found

put

HTTPcURLJavaScriptPython

PUT /api/roles/{id}/permissions/{pemId} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 38

{
  "resource": "text",
  "operation": "read"
}

No content

Delete an existing permission

delete

Authorizations

Path parameters

idstringRequired

Id of role

pemIdstringRequired

Id of permission

Responses

200

OK

400

Invalid request

404

Permission not found

delete

HTTPcURLJavaScriptPython

DELETE /api/roles/{id}/permissions/{pemId} HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

No content

Login into the cybus connectware

post

Body

usernamestringRequired

passwordstringRequired

expireTimeInHoursnumberOptional

labelstringOptional

Responses

200

OK

application/json

400

Invalid request

403

Authentication Error

post

HTTPcURLJavaScriptPython

POST /api/login HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 74

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

Return the session of the current user

get

Authorizations

Responses

200

OK

application/json

401

Unauthorized

get

HTTPcURLJavaScriptPython

GET /api/session HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

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

Return the permissions of the current user

get

Authorizations

Responses

200

OK

401

Unauthorized

get

HTTPcURLJavaScriptPython

GET /api/permissions HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

No content

Return a page of all permissions

get

Authorizations

Query parameters

idsstring[]Optional

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

200

Object with array of permissions and pagination information

application/json

400

Invalid args provided

401

Unauthorized

get

HTTPcURLJavaScriptPython

GET /api/permissions/page?rowsPerPage=1&pageNumber=1 HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

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

Return all permissions ids

get

Authorizations

Responses

200

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

application/json

401

Unauthorized

get

HTTPcURLJavaScriptPython

GET /api/permissions/ids HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

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

Logout of the cybus connectware

post

Body

tokenstringRequired

Responses

200

OK

400

Invalid request

404

Token not found

post

HTTPcURLJavaScriptPython

POST /api/logout HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "token": "text"
}

No content

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

contextstringRequired

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

Example: IoT Device Serial Number <0123456>

Responses

201

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

application/json

202

Pending. The registration request has been accepted but needs to be confirmed. Try again later.

400

Invalid Request.

409

Conflict. Might indicate that a conflicting registration is pending or a conflicting user is already existing.

422

Policy violation. A user name or a password doesn't fulfill some of the policy rules.

application/json

423

Locked. The registration endpoint is currently not open. Try again later.

post

HTTPcURLJavaScriptPython

POST /api/client-registry/register HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 1636

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

Receive a list of all pending registration requests

get

Authorizations

Responses

200

OK

application/json

401

Unauthorized

get

HTTPcURLJavaScriptPython

GET /api/client-registry HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

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

Return the current lock status of the registration endpoint

get

Authorizations

Responses

200

OK

application/json

get

HTTPcURLJavaScriptPython

GET /api/client-registry/status HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

200

OK

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

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

204

OK

401

Unauthorized

post

HTTPcURLJavaScriptPython

POST /api/client-registry/open HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "duration": 30000
}

No content

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

post

Authorizations

Responses

204

OK

401

Unauthorized

post

HTTPcURLJavaScriptPython

POST /api/client-registry/lock HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

No content

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

rolesstring[]Optional

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

Responses

204

OK

application/json

401

Unauthorized

404

Corresponding username not found

post

HTTPcURLJavaScriptPython

POST /api/client-registry/confirm HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 209

{
  "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"
        }
      ]
    }
  ],
  "mfa_is_enrolled": true,
  "enforceMFAEnrollment": true
}

List certificates

get

Authorizations

Responses

200

Array of certficates

application/json

500

Error reading certificates

get

HTTPcURLJavaScriptPython

GET /api/certificates HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

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

Deletes certificate

delete

Authorizations

Query parameters

idstringRequired

Id of certificate

Responses

200

OK

400

Invalid request

404

Certificate not found

500

Error while attempting to delete Certificate

delete

HTTPcURLJavaScriptPython

DELETE /api/certificates?id=text HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

No content

Add certificate

post

Authorizations

Body

stringOptional

Responses

201

Array of added certficates

application/json

400

Invalid request

post

HTTPcURLJavaScriptPython

POST /api/certificates HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 6

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

Returns given certificate content

get

Authorizations

Query parameters

idstringRequired

Id of certificate

Responses

200

Certificate content

application/json

Responsestring

400

Invalid request

404

Certificate not found

500

Error while attempting to delete Certificate

get

HTTPcURLJavaScriptPython

GET /api/certificates/content?id=text HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

text

Enhanced authentication of MQTT5 (not supported)

post

Body

client_idstringOptional

Responses

200

OK

application/json

post

HTTPcURLJavaScriptPython

POST /api/broker/auth/enhanced HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 68

{
  "client_id": "text",
  "properties": {
    "p_authentication_method": "text"
  }
}

200

OK

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

Return a password policy rules

get

Authorizations

Responses

200

OK

application/json

get

HTTPcURLJavaScriptPython

GET /api/policy/password HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

200

OK

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

Return a database maintenance status

get

Authorizations

Responses

200

OK

application/json

get

HTTPcURLJavaScriptPython

GET /api/maintenance/db HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

200

OK

{
  "running": true,
  "backup": {
    "id": "text",
    "succeeded": true,
    "statusMessage": "text",
    "startDate": "2025-05-17T17:36:56.589Z",
    "endDate": "2025-05-17T17:36:56.589Z"
  },
  "restore": {
    "id": "text",
    "succeeded": true,
    "statusMessage": "text",
    "startDate": "2025-05-17T17:36:56.589Z",
    "endDate": "2025-05-17T17:36:56.589Z"
  }
}

Download a database backup

get

Authorizations

Responses

200

OK

application/json

Responsestring

423

Locked. There is a database maintenance operation in the process. Try again later.

get

HTTPcURLJavaScriptPython

GET /api/maintenance/db/backup HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

text

Start a database backup

post

Authorizations

Responses

202

Accepted. Database backup started.

application/json

Responsestring

423

Locked. There is a database maintenance operation in the process. Try again later.

post

HTTPcURLJavaScriptPython

POST /api/maintenance/db/backup HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

text

Upload archive and start database restore

post

Authorizations

Responses

202

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

423

Locked. There is a database maintenance operation in the process. Try again later.

post

HTTPcURLJavaScriptPython

POST /api/maintenance/db/restore HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

No content

Enable MFA for an existing user

post

Authorizations

Responses

200

ok

application/json

400

Invalid request

409

User is already enrolled

500

Internal error

post

HTTPcURLJavaScriptPython

POST /api/mfa/enable HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

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

Validate MFA enrollment of the user

post

Authorizations

Body

otpstringRequired

Responses

200

ok

application/json

400

Invalid request

401

Invalid OTP

500

Internal error

post

HTTPcURLJavaScriptPython

POST /api/mfa/validate HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "otp": "text"
}

{
  "backupCodes": [
    "text"
  ]
}

Login user with MFA

post

Authorizations

Body

usernamestringRequired

otpstringOptional

backupCodestringOptional

secretstringRequired

Responses

200

ok

application/json

400

Invalid request

401

Invalid OTP

application/json

403

Too many failed login attempts

application/json

500

Internal error

post

HTTPcURLJavaScriptPython

POST /api/mfa/login HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 68

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

User self de-registration from MFA

post

Authorizations

Body

otpstringOptional

backupCodestringOptional

Responses

200

ok

400

Invalid request

500

Internal error

post

HTTPcURLJavaScriptPython

POST /api/mfa/disable HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "otp": "text",
  "backupCode": "text"
}

No content

Regenarete backup codes a user

post

Authorizations

Body

otpstringOptional

backupCodestringOptional

Responses

200

ok

application/json

400

Invalid request

500

Internal error

post

HTTPcURLJavaScriptPython

POST /api/mfa/regenerate/backupcodes HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "otp": "text",
  "backupCode": "text"
}

{
  "backupCodes": [
    "text"
  ]
}

Checks if a user is enrolled to mfa or not

get

Authorizations

Responses

200

ok

application/json

400

Invalid request

500

Internal error

get

HTTPcURLJavaScriptPython

GET /api/mfa/isenrolled HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Accept: */*

{
  "isEnrolled": true
}