# Offboard a Client

When a client leaves, four things have to stop: new devices registering, agents collecting, people holding access to the client, and the organization showing in your tree.
The order matters, because an organization cannot be deleted while it still has live agents.

## What the token needs

| To | Give a workspace token | With the scopes |
| - | - | - |
| Stop installs, remove agents and delete the organizations | **Deployment Manager** at the organization above the client | `fleet:write` |
| Also read and remove grants, groups and members | **Organization Administrator** there | no access limits |

A token can only remove access it could have given.
Removing a grant takes every scope the grant's role touches as well as `admin:write`. The simplest token for the access steps is one with no access limits.

## Steps

### 1. Stop new installs

This step applies only when the client has a registration token of its own.
Usually one token at a parent organization serves many clients: leave that token alone.

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

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

Filter by `organization_id` with `subtree=true` and `status=active`.

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens?organization_id=0a9e0000-0000-4000-8000-000000000101&subtree=true&status=active" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "as_of": "2026-11-10T09:01:00Z",
  "message": "registration tokens retrieved",
  "next_cursor": null,
  "registration_tokens": [
    {
      "id": "7e0c0000-0000-4000-8000-000000000301",
      "organization_id": "0a9e0000-0000-4000-8000-000000000101",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "0a9e0000-0000-4000-8000-000000000101",
        "7e0c0000-0000-4000-8000-000000000301"
      ],
      "label": "Lakeside Clinic rollout",
      "status": "active",
      "created_by_user_id": "AlexRiveraExampleUserId00001",
      "expires_at": "2026-11-30T00:00:00Z",
      "revoked_at": null,
      "revocation_reason": null,
      "use_count": 1,
      "last_used_at": "2026-11-03T12:00:00Z",
      "created_at": "2026-11-03T11:00:00Z",
      "updated_at": "2026-11-03T12:00:00Z",
      "deleted_at": null
    }
  ],
  "watermark": "2026-11-10T09:00:00Z"
}
```

Revoke each one:

**`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": "Client offboarded"
  }'
```

Response (200)

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

Do this first. No device can then register while you remove the rest.
Devices that are already registered keep working until step 2.

### 2. Remove the agents and ingest keys

Agents and ingest keys are separate lists, each with its own delete call.

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

Scope: `workspace:read`

Filter by `organization_id` with `subtree=true`. Page to the end with `cursor`: a page holds 1,000 agents by default.

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents?organization_id=0a9e0000-0000-4000-8000-000000000101&subtree=true" \
  -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
}
```

Delete each agent:

**`DELETE /workspaces/{workspace_id}/agents/{id}`** [Delete an agent](https://sparklogs.com/docs/api/reference/agents.md#delete-agent)

Scope: `fleet:write`

```bash
curl -X DELETE \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000201?uninstall=after_days&uninstall_days=7" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "agent deleted",
  "cache_clear_status": "ok"
}
```

The query parameter `uninstall` says when the software leaves the device.
A delete takes no request body.

| `uninstall` | Effect |
| - | - |
| `immediately` | The agent is told to uninstall itself the next time it checks in. A device that is switched off uninstalls when it is next on. |
| `after_days` | It uninstalls after `uninstall_days` days, from 1 to 365. |
| `never` | The record is deleted and the software stays installed, idle. |

Leave `uninstall` out and the agent uninstalls after 60 days.
Add `uninstall_purge=true` to remove the agent's local data from the device as well. It cannot be combined with `never`.

Uninstalling at once and removing local data:

```bash
curl -X DELETE \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000202?uninstall=immediately&uninstall_purge=true" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

A deleted agent's check-ins are refused, and it cannot register again.

Then the ingest keys:

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

Scope: `workspace:read`

Filter by `organization_id` with `subtree=true`, and page to the end.

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys?organization_id=0a9e0000-0000-4000-8000-000000000101&subtree=true" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "as_of": "2026-11-10T15:05:00Z",
  "ingest_keys": [
    {
      "id": "a9e70000-0000-4000-8000-000000000205",
      "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
      "name": "Lakeside Clinic firewall",
      "description": "Syslog from the front office firewall",
      "organization_id": "0a9e0000-0000-4000-8000-000000000101",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "0a9e0000-0000-4000-8000-000000000101",
        "a9e70000-0000-4000-8000-000000000205"
      ],
      "data_status": "online",
      "last_data_at": "2026-11-10T15:00:00Z",
      "created_at": "2026-11-03T14:00:00Z",
      "updated_at": "2026-11-10T15:00:00Z",
      "deleted_at": null,
      "organization_deleted_at": null
    }
  ],
  "message": "ingest keys retrieved",
  "next_cursor": null
}
```

**`DELETE /workspaces/{workspace_id}/ingest-keys/{id}`** [Delete an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#delete-ingest-key)

Scope: `fleet:write`

Once per ingest key. The call takes no body.

```bash
curl -X DELETE \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000205" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "ingest key deleted",
  "cache_clear_status": "ok"
}
```

A deleted agent or ingest key is refused at once when `cache_clear_status` in the response is `ok`. Otherwise it can keep working for up to two hours.

### 3. Remove access given at the client

This step applies only when you gave access at this client specifically.
Access given at a parent organization, the usual arrangement, needs no change.

Deleting an organization does not remove the grants that name it.
A grant over a deleted organization still applies: its holder could restore the organization, for example.
Find those grants and remove them.

First list the client's organizations, to know which ids to look for: list with `root_id` set to the client and `deleted=include`.

Remove only grants that name those organizations.
A grant over every organization, or over an organization above the client, belongs to your own staff and covers other clients too. Leave those grants in place.

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

Scope: any of `admin:read`, `admin:write`

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "members retrieved",
  "members": [
    {
      "user_id": "SamChenExampleUserId00000002",
      "email": "sam.chen@example.com",
      "full_name": "Sam Chen",
      "display_name": "Sam",
      "is_self": false,
      "created_at": "2026-11-02T10:00:00Z",
      "deleted_at": null,
      "grants": [
        {
          "id": "6a170000-0000-4000-8000-000000000502",
          "role_id": "engineer",
          "scope": {
            "kind": "selected",
            "org_ids": [
              "0a9e0000-0000-4000-8000-000000000101"
            ],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "groups": [
        {
          "id": "9a0b0000-0000-4000-8000-000000000401",
          "name": "Helpdesk Tier 1"
        }
      ]
    }
  ],
  "next_cursor": null
}
```

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

Scope: any of `admin:read`, `admin:write`

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "groups": [
    {
      "id": "9a0b0000-0000-4000-8000-000000000401",
      "name": "Helpdesk Tier 1",
      "created_at": "2026-11-02T10:00:00Z",
      "updated_at": "2026-11-02T10:00:00Z",
      "grants": [
        {
          "id": "6a170000-0000-4000-8000-000000000503",
          "role_id": "analyst_no_raw_logs",
          "scope": {
            "kind": "selected",
            "org_ids": [
              "0a9e0000-0000-4000-8000-000000000101",
              "0a9e0000-0000-4000-8000-000000000105"
            ],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "member_count": 1
    },
    {
      "id": "9a0b0000-0000-4000-8000-000000000402",
      "name": "Project Engineers",
      "created_at": "2026-11-02T10:00:00Z",
      "updated_at": "2026-11-02T10:00:00Z",
      "grants": [
        {
          "id": "6a170000-0000-4000-8000-000000000505",
          "role_id": "engineer",
          "scope": {
            "kind": "selected",
            "org_ids": [
              "0a9e0000-0000-4000-8000-000000000103"
            ],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "member_count": 0
    }
  ],
  "message": "workspace groups retrieved",
  "next_cursor": null
}
```

Members, groups and pending invitations each carry grants.
Look for grants whose organizations include the client or anything below it.
Then act on what you find:

| You find | Do |
| - | - |
| A grant that names only this client's organizations | [Delete the grant](https://sparklogs.com/docs/api/reference/grants.md#delete-grant). |
| A grant that names this client and others | [Update the grant](https://sparklogs.com/docs/api/reference/grants.md#update-grant) to drop this client's organizations. |
| A grant whose `scope` field has `inherited` or `other_orgs` set | Skip it. The grant covers organizations the token cannot see. `other_orgs` means some of its organizations are left out of the list. `inherited` means it was given at an organization above what the token can see. Removing it returns 403 `APP_API_ERR_BEYOND_OWN_AUTHORITY`. |
| A group whose every grant names only this client's organizations | [Delete the group](https://sparklogs.com/docs/api/reference/groups.md#delete-group). Its grants go with it. |
| A group with `other_grants` set | Do not delete the group. It holds a grant the token is not shown, and deleting a group requires access over every grant the group holds. Delete or narrow the grants you can see, one at a time. |
| A pending invitation whose grants name this client | [Delete the invitation](https://sparklogs.com/docs/api/reference/invitations.md#delete-invitation). If it also named other clients, invite the person again with those. |
| A person who worked for the client and has no other access | [Remove the member](https://sparklogs.com/docs/api/reference/members.md#delete-member). Decide this by hand: nothing in the data says who a person works for. Removing a member also deletes their personal tokens and connected apps. |

Deleting a grant that names only this client:

**`DELETE /workspaces/{workspace_id}/grants/{id}`** [Remove a grant](https://sparklogs.com/docs/api/reference/grants.md#delete-grant)

Scope: `admin:write`

This example's token carries: `workspace:read`, `events:query`, `events:read`, `devices:read`, `fleet:write`, `admin:write`

```bash
curl -X DELETE \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/6a170000-0000-4000-8000-000000000502" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "grant deleted",
  "cache_clear_status": "ok"
}
```

Narrowing a grant that names this client and others:

**`PUT /workspaces/{workspace_id}/grants/{id}`** [Replace a grant](https://sparklogs.com/docs/api/reference/grants.md#update-grant)

Scope: `admin:write`

This example's token carries: `workspace:read`, `events:query`, `devices:read`, `admin:write`

```bash
curl -X PUT \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/grants/6a170000-0000-4000-8000-000000000503" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": "analyst_no_raw_logs",
    "scope": {
      "kind": "selected",
      "org_ids": [
        "0a9e0000-0000-4000-8000-000000000105"
      ]
    }
  }'
```

Response (200)

```json
{
  "message": "grant replaced",
  "id": "6a170000-0000-4000-8000-000000000503",
  "cache_clear_status": "ok"
}
```

A workspace token's grants do not show up in these lists.
Review workspace tokens in the app.

Keep a list of everything you skipped and give it to a person.
A skipped grant still reaches the client's organizations, deleted or not.

### 4. Delete the organizations

**`DELETE /workspaces/{workspace_id}/organizations/{id}`** [Delete an organization](https://sparklogs.com/docs/api/reference/organizations.md#delete-organization)

Scope: `fleet:write`

```bash
curl -X DELETE \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000102" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "organization deleted",
  "cache_clear_status": "ok"
}
```

Using the list from step 3, delete the deepest organizations first (the longest `path`), then the client itself.
An organization with a live organization, agent or ingest key anywhere below it returns 409 `APP_API_ERR_CANNOT_DELETE_ORG_NOT_EMPTY`.
Registration tokens and grants do not block the delete.
This is the refusal when something live is left:

Response (409)

```json
{
  "error": "cannot delete organization because it is not empty: it still holds live agents, ingest keys or child organizations",
  "error_code": "APP_API_ERR_CANNOT_DELETE_ORG_NOT_EMPTY"
}
```

Then the client itself:

**`DELETE /workspaces/{workspace_id}/organizations/{id}`** [Delete an organization](https://sparklogs.com/docs/api/reference/organizations.md#delete-organization)

Scope: `fleet:write`

```bash
curl -X DELETE \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations/0a9e0000-0000-4000-8000-000000000101" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "organization deleted",
  "cache_clear_status": "ok"
}
```

Deleting an organization marks it deleted: it and its data no longer show in the app or in the default lists.
The delete does not erase the data.
The organization can still be listed with `deleted=include`, read and restored.

## If a step fails

| Step | Response | Cause and fix |
| - | - | - |
| Any | 403 with `cause` `token_scope` | The token lacks the scope named in `required_scope`. |
| 1 | 409 `APP_API_ERR_CONFLICT` | The registration token is deleted. There is nothing left to revoke. |
| 2 (agents) | 400 naming a parameter | `uninstall_days` or `uninstall_purge` was sent without `uninstall`, a value is not one the call takes, or the request has a body. |
| 3 | 403 `APP_API_ERR_BEYOND_OWN_AUTHORITY` | The grant reaches beyond the token. Skip it and report it. |
| 4 | 409 `APP_API_ERR_CANNOT_DELETE_ORG_NOT_EMPTY` | Something live is still below the organization. Go back to step 2. |

## Idempotency (safety of repeated API calls)

Revoking a revoked token, or deleting a deleted agent, ingest key or organization, returns 200 again.
Deleting a grant, a group or a member cannot be undone, so deleting one a second time returns 404.
Treat that 404 as done.

## If you need to restore a client

Restore in the opposite order, top down:

1. [Restore the organization](https://sparklogs.com/docs/api/reference/organizations.md#restore-organization), parents before children.
2. List the deleted agents and the deleted ingest keys with `deleted=include`, then [restore each agent](https://sparklogs.com/docs/api/reference/agents.md#restore-agent) and [each ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#restore-ingest-key). Restoring an agent cancels a pending uninstall. If the software is already gone from the device, install it again. A restore returns 409 when the device has since registered again as a new agent.
3. Create a new registration token. A revoked token stays revoked. One that was not revoked works again once its organization is restored.

Grants and groups that were deleted cannot be restored: create them again.
A removed member has to be invited again.

## What the API does not do

- It does not list the grants given at one organization. Step 3 scans members and groups.
- It does not delete an organization and everything in it in one call: each agent, ingest key and organization takes its own call.
- Revoking a registration token cannot be undone.
- It does not purge a client's data.

---

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