Registering a Client
Issue a client its registration token and turn that into a working credential.
There is currently no "Add RPA Client" button in the Mandala UI. Both steps below are authenticated API calls. A dedicated UI for the admin-side step is expected in a future update -- this page documents the only way to do it today.
Bringing a new client machine online is a two-step handshake: a workspace admin registers the client and receives a short-lived registration token, and the client machine itself then trades that token, once, for a long-lived credential it keeps from then on.
Admin registers the client (browser session, workspace admin permission required)
Client exchanges the token for a credential (no browser session -- this is the client program itself, calling out over plain HTTPS)
Step 1: Register the Client
A workspace admin calls:
POST /api/rpa/clients// Request body
{
"workspaceId": "<your workspace id>",
"name": "Warehouse ERP Machine"
}// Response (201)
{
"success": true,
"data": {
"id": "<new client id>",
"name": "Warehouse ERP Machine",
"status": "pending",
"createdAt": "2026-08-23T00:00:00.000Z",
"registrationToken": "<shown exactly once>",
"registrationTokenExpiresAt": "2026-08-23T00:10:00.000Z"
}
}registrationToken is shown exactly once, in this response, and is never stored in plaintext or retrievable again. Copy it immediately. It also expires in 10 minutes and can only be exchanged once -- if it expires unused, register the client again to get a fresh one.
This call requires admin permission on the target workspace; anything less is rejected. The new client is created with status: "pending" and isn't usable for dispatch until it completes Step 2.
Step 2: Exchange the Token for a Credential
The client machine itself -- not a browser -- makes this call, using the id and registrationToken from Step 1:
POST /api/rpa/clients/{id}/exchange// Request body
{
"registrationToken": "<the token from Step 1>",
"machineFingerprint": { "...": "optional, arbitrary machine-identifying data" }
}// Response
{
"success": true,
"data": {
"clientId": "<the client id>",
"credential": "<shown exactly once -- store this securely on the machine>"
}
}credential is shown exactly once, in this response, and is never retrievable again after this call. This is what your client program authenticates with from now on -- see Client Protocol for how it's used, and Security for how to store it. This call has no session of its own; knowing the registration token is what authorizes it, which is exactly why that token is short-lived and single-use.
Once this succeeds, the client's status flips to active and it's ready to connect -- see Client Protocol for the connection flow itself.
Machine Naming
name is just a label an admin picks to tell clients apart in the settings dashboard -- it isn't parsed or used for routing. Name machines for what they have access to (e.g. "Warehouse ERP Machine", "Finance Desktop -- Building 2") rather than something generic; a workspace can register any number of clients.