Self-Registering Clients via REST API
Flexible and secure client self-registration with role, permission, and certificate configuration.
The REST API registration method enables advanced client configuration during the self-registration process. With this method, clients (e.g. agents) can include additional information, such as context details, role requests, permission specifications, and certificate signing requests (CSRs), in their registration payload.
When using certificate signing requests (CSR), the Common Name (CN) in the CSR must match the username in the payload and must not be empty. Otherwise, the request will be rejected.
Registration Workflow
The client self-registration process via REST API follows these steps:

The client sends an initial registration request to Connectware with credentials and optionally requested roles and permissions.
If the registry endpoint is locked (default), Connectware returns a
423 Locked
response.The Connectware administrator unlocks the registry endpoint for five minutes.
The client resends the registration request and receives a
202 Accepted
(pending) response.The client polls at regular intervals by resending the same request.
The Connectware administrator reviews and approves the pending request.
Upon the next poll, the client receives a
201 Created
response indicating successful registration.If the registration used a CSR, the signed certificate is included in the response.
The client can now authenticate using standard mechanisms.
Initiating the Self-Registration (Client)
Prerequisite
The registration API must be unlocked by a Connectware administrator.
Initiating the Self-Registration
To initiate the self-registration, the client sends a
POST
request to the/api/client-registry/register
endpoint. The client can include context details, role requests, permission specifications, and certificate signing requests (CSRs) with its registration via the API parameters.
Example for HTTP clients
Example with username, password, and context.
curl --insecure --location https://localhost/api/client-registry/register --header 'Content-Type: application/json' --data-raw '{
"username": "sensor-0003",
"password": "3f9a7b2cTe!rRTt56fT",
"context": "Temperature sensor for line 53c"
}
Example with username, password, role, and context.
curl --insecure --location https://localhost/api/client-registry/register --header 'Content-Type: application/json' --data-raw '{
"username": "sensor-0003",
"password": "3f9a7b2cTe!rRTt56fT",
"roles": ["minimum"],
"context": "Serial number 35350"
}
For detailed information about the Client Registry REST API parameters, see Auth Server API Reference.
Required and Optional Parameters
Either a
password
or acsr
(certificate signing request) must be provided — but not both.roles
andpermissions
define the access permissions that the client is requesting.context
provides optional metadata to help administrators identify the source or purpose of the request.
Possible Responses
201 Created
Registration granted; the client can now authenticate.
202 Accepted
Registration is pending admin approval.
400 Bad Request
Malformed or incomplete request.
409 Conflict
Username already exists or request is duplicated.
422 Unprocessable Entity
Username or password violates policy requirements.
423 Locked
Registration endpoint is currently locked.
Approving Self-Registration Requests (Admin)
After a client attempts registration, the Connectware admin must approve the request before the client can access the system.
Approving Self-Registration Requests via REST API
To approve self-registration requests via REST API, refer to the
Confirm a single authentication request
parameter documented in the Auth Server API Reference.
Approving Self-Registration Requests via Admin UI
In the Client Registry View, click the Unlock button to temporarily unlock the self-registration. The registry will remain open for five minutes and will automatically lock again after this period. You can manually lock the registry by clicking the Lock button.
Locate the pending client request in the table.

Click the registration request in the list to open the Grant Access dialog.
In the Grant Access dialog, inspect the client request details, then click Allow to approve the registration.

In the navigation panel, click User and verify that the newly created user appears in the users list.
Last updated
Was this helpful?