Skip to main content

Onboard a Client

This example shows how to create a new client's organization in SparkLogs, create the registration token your RMM needs to install agents there, and confirm the devices registered. Run it from the automation that already fires when a company is added in your PSA.

Most MSPs do not need this. Normally a client's organization is created automatically when its first agent registers, from the RMM or PSA client id on the install command: see Deployment scope. Use this example when you want the organization to exist before any agent is deployed.

What the token needs​

Use a workspace token. The automation then does not depend on one person's account.

Give itWhy
The Deployment Manager role at the organization that holds your clientsIt can create organizations there and create registration tokens, and it cannot read log data. Find that organization's id once, in the app or with list organizations.
The scope fleet:writeIt carries creating organizations and everything in fleet:deploy.

Every token also carries workspace:read, which the lookups in step 2 use. If organizations are created another way and this automation only deploys agents, fleet:deploy is enough.

A client created at the top level of the workspace, with no parent, needs the role across every organization.

Steps​

1. Find the workspace id​

GET/credential
Read credential metadata

This example's token carries: workspace:readfleet:write

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/credential" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "credential": {    "kind": "workspace_key",    "credential_id": "4b1d0000-0000-4000-8000-000000000801",    "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",    "region_id": "us-central",    "scope_restriction": "listed",    "scopes": [      "workspace:read",      "fleet:write"    ],    "expires_at": "2027-11-01T09:00:00Z"  },  "message": "credential retrieved"}

Every later path needs workspace_id from this response. Store it. The id does not change.

2. Check whether the client already exists​

GET/workspaces/{workspace_id}/organizations
List organizations

Scope: workspace:read

By the PSA id, with deleted=include.

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations?psa_client_id=10042&deleted=include" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "message": "organizations retrieved",  "next_cursor": null,  "organizations": [],  "watermark": "2026-11-02T08:00:00Z"}
GET/workspaces/{workspace_id}/organizations
List organizations

Scope: workspace:read

By the RMM id, with deleted=include.

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations?rmm_client_id=LAKESIDE-01&deleted=include" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "message": "organizations retrieved",  "next_cursor": null,  "organizations": [],  "watermark": "2026-11-02T08:00:00Z"}

Creating an organization twice makes two organizations, because names and client ids are not unique. So look first, by both ids. A lookup with both filters in one call finds only an organization that has both ids. Make two calls. Add parent_id or root_id to either call to look only under one part of your tree.

Both ids matter because of how an agent installs. The install command carries an RMM id or a PSA id, and the agent joins the organization that has that id. If no organization has it, the install creates a new organization. An organization your PSA sync created with only a PSA id is therefore not found by an install that passes the RMM id, and you end up with two.

The lookups returnDo
NothingGo on to step 3.
One live organization with both idsThe client exists. Skip to step 4 with its id.
One live organization missing one idUpdate it to record the missing id, then skip to step 4.
One live organization that has a different value for the other idStop. Either the ids are crossed in your PSA or RMM, or this is another client.
One deleted organizationRestore it, then treat it as live. An install that matches only a deleted organization is refused until it is restored.
One live organization and a deleted oneUse the live one. An install prefers it too.
Two or more live organizationsStop. A person has to decide which is the client.

3. Create the organization​

POST/workspaces/{workspace_id}/organizations
Create an organization

Scope: fleet:write

Request
curl -X POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "description": "Family practice, two sites",    "name": "Lakeside Clinic",    "parent_id": "0a9e0000-0000-4000-8000-000000000100",    "psa_client_id": "10042",    "rmm_client_id": "LAKESIDE-01"  }'
Response 200
{  "message": "organization created",  "id": "0a9e0000-0000-4000-8000-000000000101",  "cache_clear_status": "ok"}

Send parent_id (the organization that holds your clients), name, and both psa_client_id and rmm_client_id. Keep the id from the response: it is the client's organization from now on.

For a client with several sites, create one organization per site with parent_id set to the client's id. Give each site the id your RMM uses for that site.

POST/workspaces/{workspace_id}/organizations
Create an organization

Scope: fleet:write

Request
curl -X POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "name": "Finance",    "parent_id": "0a9e0000-0000-4000-8000-000000000101"  }'
Response 200
{  "message": "organization created",  "id": "0a9e0000-0000-4000-8000-000000000102",  "cache_clear_status": "ok"}

4. Create a registration token​

We normally recommend one registration token for a whole group of clients, created at their parent organization. One RMM deployment script then serves every client. If you already have that token, skip this step and use it. A token of its own for one client, as below, is an option when you want to limit or revoke installs for that client alone.

POST/workspaces/{workspace_id}/registration-tokens
Create a registration token

Scope: any of fleet:deployfleet:write

Request
curl -X POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "expires_at": "2026-11-30T00:00:00Z",    "label": "Lakeside Clinic rollout",    "organization_id": "0a9e0000-0000-4000-8000-000000000101"  }'
Response 200
Cache-Control: no-store
{  "message": "registration token created",  "id": "7e0c0000-0000-4000-8000-000000000301",  "token": "EXAMPLE-REGISTRATION-TOKEN-NOT-REAL"}

Send organization_id (the client), a label that says what it is for, and expires_at a few weeks out. The response carries token, the secret the installer presents. A token with an expiry stops working on that date, even if you forget to revoke it.

If the response is lost, do not create another. List the client's registration tokens, find yours by its label, and reveal its secret:

GET/workspaces/{workspace_id}/registration-tokens/{id}/secret
Read a registration token's secret

Scope: any of fleet:deployfleet:write

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/secret" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
Cache-Control: no-store
{  "message": "registration token retrieved",  "token": "EXAMPLE-REGISTRATION-TOKEN-NOT-REAL"}

Give each rollout its own label, and only one token will match.

5. Deploy the agent through your RMM​

This step is not an API call. Put the token into the install command your RMM runs on the client's devices:

msiexec /i SparkLogsAgent.msi /qn /norestart EULA=ACCEPT REGISTRATION_TOKEN=<token> RMMCLIENTID=%CLIENT_ID% CLIENTNAME="%CLIENT_NAME%"

To read the installer, its checksum and a ready command from the API, see Fetch latest agent installer. Deploy the agent has the script for each RMM. The token is a secret on that command line: check whether your RMM writes its scripts' command lines to a log that others can read.

Each device then registers itself. It joins the organization whose rmm_client_id or psa_client_id matches the id on the command line. Only the token's organization and the organizations below it are searched. Step 3 recorded those ids for this purpose.

Two cases behave differently:

  • An id that matches nothing creates a new organization under the token's organization, named from CLIENTNAME. If devices show up in an organization you did not create, the id on the command line and the id on the organization differ.
  • No id on the command line fails the install. A new install needs RMMCLIENTID or PSACLIENTID. To put devices straight into the token's own organization, pass USEPARENTORG=1 in their place.

6. Confirm the devices arrived​

GET/workspaces/{workspace_id}/agents
List agents

Scope: workspace:read

Filter by registration_token_id to see exactly the devices this rollout registered, or by organization_id with subtree=true for everything at the client.

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents?registration_token_id=7e0c0000-0000-4000-8000-000000000301" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "agents": [    {      "id": "a9e70000-0000-4000-8000-000000000201",      "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",      "name": "FIN-LT-04",      "organization_id": "0a9e0000-0000-4000-8000-000000000102",      "path": [        "0a9e0000-0000-4000-8000-000000000100",        "0a9e0000-0000-4000-8000-000000000101",        "0a9e0000-0000-4000-8000-000000000102",        "a9e70000-0000-4000-8000-000000000201"      ],      "reported_state": "running",      "agent_status": "online",      "reported_state_changed_at": "2026-11-03T12:00:00Z",      "collection_status": "healthy",      "stuck_reason": null,      "last_data_at": "2026-11-10T15:00:00Z",      "last_heartbeat_at": "2026-11-10T15:00:00Z",      "host_class": "workstation",      "reported_hostname": "fin-lt-04",      "rmm_device_id": null,      "psa_device_id": null,      "agent_version": "1.14.4",      "os_family": "windows",      "os_version": "10.0.22631",      "created_at": "2026-11-03T12:00:00Z",      "updated_at": "2026-11-10T15:00:00Z",      "deleted_at": null,      "organization_deleted_at": null    }  ],  "as_of": "2026-11-10T15:05:00Z",  "message": "agents retrieved",  "next_cursor": null}

While the rollout runs, poll every five minutes. Agents check in about that often. Read these fields for each agent:

FieldTells you
agent_statusonline once the agent is checking in. never_seen means it registered and has not checked in yet.
last_heartbeat_atWhen the agent last checked in. Agents check in about every five minutes.
collection_statusWhether collection is working: healthy, behind, onboarding, degraded or unknown. It is null until the agent first reports. Treat every value except healthy as not yet healthy.
last_data_atWhen log data last arrived.

To see how many devices used the token, read the registration token and look at use_count and last_used_at.

7. Close the token​

A token created with expires_at stops registering devices at that moment, and there is nothing to do. To close it sooner, revoke it:

POST/workspaces/{workspace_id}/registration-tokens/{id}/revoke
Revoke a registration token

Scope: any of fleet:deployfleet:write

Request
curl -X POST \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/revoke" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "reason": "Rollout finished"  }'
Response 200
{  "message": "registration token revoked"}

Revoking stops new installs. Devices that already registered keep working.

If a step fails​

StepResponseCause and fix
3403 APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONThe token cannot create under that parent, or parent_id is not an organization in this workspace. Check the id and the token's role there.
3403 APP_API_ERR_NO_PRIVILEGE_ON_ALL_ORGANIZATIONSparent_id was left out, and creating at the top level needs the role across every organization.
3 or 4403 with cause token_scopeThe token lacks the scope named in required_scope.
3400 naming a fieldA required field is missing, a client id is longer than 256 characters or a name longer than 128 characters, or the body has a field the call does not know.
3400 naming parent_idThe parent is deleted, or the new organization would sit more than 25 levels deep.
4400 naming organization_idThe organization is deleted.
4400 naming expires_atThe time is not RFC 3339.
5The installer reports that the token is revoked, expired or unknownCreate a new token (step 4) and redeploy.
5The installer reports a region mismatchThe token belongs to a workspace in another region. Use a registration token from the right workspace.
5The installer reports that the organization is deletedThe id matched a deleted organization, or the token's own organization is deleted. Restore it, or correct the id.

Idempotency (safety of repeated API calls)​

Steps 1, 2, 6 and 7 are safe to repeat: three only read, and step 7 sets a state that may already be set. Step 5 is not an API call. Steps 3 and 4 create something new on every call, so check before repeating them:

  • Step 3: repeat step 2 first.
  • Step 4: list the client's registration tokens and look for your label. Reuse one whose status is active by revealing its secret. One that is expired can be made active again by updating expires_at to a later time. One that is revoked stays revoked: create a new one.

What the API does not do​

  • To match an agent to its device in your RMM or PSA, pass the device's id to the installer as RMMDEVICEID or PSADEVICEID (install properties), then filter the list of agents by rmm_device_id or psa_device_id. Without a device id, match the client first and then reported_hostname within that one client, and expect that two agents can report the same name. Hostnames repeat across clients: do not match on hostname alone.