Skip to main content

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​

ToGive a workspace tokenWith the scopes
Stop installs, remove agents and delete the organizationsDeployment Manager at the organization above the clientfleet:write
Also read and remove grants, groups and membersOrganization Administrator thereno 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

Scope: any of fleet:deployfleet:write

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

Request
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
{  "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

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": "Client offboarded"  }'
Response 200
{  "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

Scope: workspace:read

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

Request
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
{  "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

Scope: fleet:write

Request
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
{  "message": "agent deleted",  "cache_clear_status": "ok"}

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

uninstallEffect
immediatelyThe 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_daysIt uninstalls after uninstall_days days, from 1 to 365.
neverThe 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:

Request
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

Scope: workspace:read

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

Request
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
{  "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

Scope: fleet:write

Once per ingest key. The call takes no body.

Request
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
{  "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

Scope: any of admin:readadmin:write

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "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

Scope: any of admin:readadmin:write

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "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 findDo
A grant that names only this client's organizationsDelete the grant.
A grant that names this client and othersUpdate the grant to drop this client's organizations.
A grant whose scope field has inherited or other_orgs setSkip 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 organizationsDelete the group. Its grants go with it.
A group with other_grants setDo 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 clientDelete the invitation. If it also named other clients, invite the person again with those.
A person who worked for the client and has no other accessRemove the 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

Scope: admin:write

This example's token carries: workspace:readevents:queryevents:readdevices:readfleet:writeadmin:write

Request
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
{  "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

Scope: admin:write

This example's token carries: workspace:readevents:querydevices:readadmin:write

Request
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
{  "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

Scope: fleet:write

Request
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
{  "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
{  "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

Scope: fleet:write

Request
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
{  "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​

StepResponseCause and fix
Any403 with cause token_scopeThe token lacks the scope named in required_scope.
1409 APP_API_ERR_CONFLICTThe registration token is deleted. There is nothing left to revoke.
2 (agents)400 naming a parameteruninstall_days or uninstall_purge was sent without uninstall, a value is not one the call takes, or the request has a body.
3403 APP_API_ERR_BEYOND_OWN_AUTHORITYThe grant reaches beyond the token. Skip it and report it.
4409 APP_API_ERR_CANNOT_DELETE_ORG_NOT_EMPTYSomething 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, parents before children.
  2. List the deleted agents and the deleted ingest keys with deleted=include, then restore each agent and each 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.