Self-Registering Clients via REST API

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.

Registration Workflow

The client self-registration process via REST API follows these steps:

1. The client sends an initial registration request to Connectware with credentials and optionally requested roles and permissions.

2. If the registry endpoint is locked (default), Connectware returns a 423 Locked response.

3. The Connectware administrator unlocks the registry endpoint for five minutes.

4. The client resends the registration request and receives a 202 Accepted (pending) response.

5. The client polls at regular intervals by resending the same request.

6. The Connectware administrator reviews and approves the pending request.

7. Upon the next poll, the client receives a 201 Created response indicating successful registration.

8. If the registration used a CSR, the signed certificate is included in the response.

9. 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 a csr (certificate signing request) must be provided — but not both.

• roles and permissions 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

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

1. 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.

2. Locate the pending client request in the table.

1. Click the registration request in the list to open the Grant Access dialog.

2. In the Grant Access dialog, inspect the client request details, then click Allow to approve the registration.

1. In the navigation panel, click User and verify that the newly created user appears in the users list.