# 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](https://sparklogs.com/docs/agents/deployment-scope.md).
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 it | Why |
| - | - |
| The **Deployment Manager** role at the organization that holds your clients | It 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](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations). |
| The scope `fleet:write` | It 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](https://sparklogs.com/docs/api/reference/credential.md#read-credential)

This example's token carries: `workspace:read`, `fleet:write`

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/credential" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "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](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)

Scope: `workspace:read`

By the PSA id, with `deleted=include`.

```bash
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)

```json
{
  "message": "organizations retrieved",
  "next_cursor": null,
  "organizations": [],
  "watermark": "2026-11-02T08:00:00Z"
}
```

**`GET /workspaces/{workspace_id}/organizations`** [List organizations](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)

Scope: `workspace:read`

By the RMM id, with `deleted=include`.

```bash
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)

```json
{
  "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 return | Do |
| - | - |
| Nothing | Go on to step 3. |
| One live organization with both ids | The client exists. Skip to step 4 with its `id`. |
| One live organization missing one id | [Update it](https://sparklogs.com/docs/api/reference/organizations.md#update-organization) to record the missing id, then skip to step 4. |
| One live organization that has a different value for the other id | Stop. Either the ids are crossed in your PSA or RMM, or this is another client. |
| One deleted organization | [Restore it](https://sparklogs.com/docs/api/reference/organizations.md#restore-organization), 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 one | Use the live one. An install prefers it too. |
| Two or more live organizations | Stop. A person has to decide which is the client. |

### 3. Create the organization

**`POST /workspaces/{workspace_id}/organizations`** [Create an organization](https://sparklogs.com/docs/api/reference/organizations.md#create-organization)

Scope: `fleet:write`

```bash
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)

```json
{
  "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](https://sparklogs.com/docs/api/reference/organizations.md#create-organization)

Scope: `fleet:write`

```bash
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)

```json
{
  "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](https://sparklogs.com/docs/api/reference/registration-tokens.md#create-registration-token)

Scope: any of `fleet:deploy`, `fleet:write`

```bash
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)

Headers: `Cache-Control: no-store`

```json
{
  "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](https://sparklogs.com/docs/api/reference/registration-tokens.md), find yours by its label, and reveal its secret:

**`GET /workspaces/{workspace_id}/registration-tokens/{id}/secret`** [Read a registration token's secret](https://sparklogs.com/docs/api/reference/registration-tokens.md#reveal-registration-token)

Scope: any of `fleet:deploy`, `fleet:write`

```bash
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)

Headers: `Cache-Control: no-store`

```json
{
  "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:

```bat
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](https://sparklogs.com/docs/api/use-cases/deploy-agents.md).
[Deploy the agent](https://sparklogs.com/docs/agents.md) 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](https://sparklogs.com/docs/api/reference/agents.md#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.

```bash
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)

```json
{
  "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:

| Field | Tells you |
| - | - |
| `agent_status` | `online` once the agent is checking in. `never_seen` means it registered and has not checked in yet. |
| `last_heartbeat_at` | When the agent last checked in. Agents check in about every five minutes. |
| `collection_status` | Whether 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_at` | When log data last arrived. |

To see how many devices used the token, [read the registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md) 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](https://sparklogs.com/docs/api/reference/registration-tokens.md#revoke-registration-token)

Scope: any of `fleet:deploy`, `fleet:write`

```bash
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)

```json
{
  "message": "registration token revoked"
}
```

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

## If a step fails

| Step | Response | Cause and fix |
| - | - | - |
| 3 | 403 `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` | The 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. |
| 3 | 403 `APP_API_ERR_NO_PRIVILEGE_ON_ALL_ORGANIZATIONS` | `parent_id` was left out, and creating at the top level needs the role across every organization. |
| 3 or 4 | 403 with `cause` `token_scope` | The token lacks the scope named in `required_scope`. |
| 3 | 400 naming a field | A 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. |
| 3 | 400 naming `parent_id` | The parent is deleted, or the new organization would sit more than 25 levels deep. |
| 4 | 400 naming `organization_id` | The organization is deleted. |
| 4 | 400 naming `expires_at` | The time is not RFC 3339. |
| 5 | The installer reports that the token is revoked, expired or unknown | Create a new token (step 4) and redeploy. |
| 5 | The installer reports a region mismatch | The token belongs to a workspace in another region. Use a registration token from the right workspace. |
| 5 | The installer reports that the organization is deleted | The 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](https://sparklogs.com/docs/agents/download-verify.md#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.

---

Source: <https://sparklogs.com/docs/api/use-cases/onboard-client>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
