Offboard a Technician
When a technician leaves, one call removes them from the workspace together with the access, tokens and connected apps they held in it. This example shows how to find the person, record what they had, remove them, and confirm the result.
What the token needs
| Give a workspace token | With the scope |
|---|---|
| Organization Administrator at an organization above every client the person can reach | no access limits |
A token can only remove a person whose access sits inside its own.
If the person holds a grant, or belongs to a group, that reaches beyond the token, the removal returns 403 APP_API_ERR_BEYOND_OWN_AUTHORITY.
No API token can remove a person who holds the Administrator role over every organization. An administrator does that in the app.
Steps
1. Find the person
/workspaces/{workspace_id}/members Scope: any of admin:readadmin:write
Filter by email.
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members?email=sam.chen%40example.com" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members?email=sam.chen%40example.com" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "email": "sam.chen@example.com", },)response.raise_for_status(){ "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}The email filter matches exactly, ignoring case.
Keep the person's user_id.
- An email with no member belongs to someone who never accepted. List the invitations with the same
emailfilter, then delete the invitation, and there is nothing else to remove. - A token with access to only part of the tree sees a member only when one of the member's grants, their own or a group's, names an organization inside that part.
2. Record their groups
/workspaces/{workspace_id}/groups Scope: any of admin:readadmin:write
Pass fields with members added to the default fields.
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups?fields=id%2Cname%2Ccreated_at%2Cupdated_at%2Cgrants%2Cother_grants%2Cmember_count%2Cmembers" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups?fields=id%2Cname%2Ccreated_at%2Cupdated_at%2Cgrants%2Cother_grants%2Cmember_count%2Cmembers" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "fields": "id,name,created_at,updated_at,grants,other_grants,member_count,members", },)response.raise_for_status(){ "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, "members": [ { "user_id": "SamChenExampleUserId00000002", "email": "sam.chen@example.com", "full_name": "Sam Chen", "display_name": "Sam" } ] }, { "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, "members": [] } ], "message": "workspace groups retrieved", "next_cursor": null}This step is optional.
The removal in step 3 takes the person out of every group, so list the groups with their members first if you want a record of what the person could reach.
The member's groups leaves out any group the token cannot see.
3. Remove the member
/workspaces/{workspace_id}/members/{user_id} Scope: admin:write
This example's token carries: workspace:readevents:queryevents:readdevices:readfleet:writeadmin:write
- curl
- PowerShell
- Python
curl -X DELETE \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members/SamChenExampleUserId00000002" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Delete ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members/SamChenExampleUserId00000002" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.delete( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members/SamChenExampleUserId00000002" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "user removed from workspace", "cache_clear_status": "ok"}This one call removes the membership and, with it:
- the person's own grants;
- their place in every group;
- their personal API tokens and connected apps in this workspace, including any app connection they had started and not finished.
When cache_clear_status in the response is ok, the person's app session and tokens are refused from their next call.
Otherwise that can take up to 15 minutes.
4. Check the member list
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members?email=sam.chen%40example.com" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members?email=sam.chen%40example.com" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "email": "sam.chen@example.com", },)response.raise_for_status(){ "message": "members retrieved", "members": [], "next_cursor": null}The person is no longer under members.
Invitations they sent stay pending and can still be accepted.
Each of those has sender_removed set to true: delete any you no longer want.
5. Check the audit log
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/audit-events?target_id=SamChenExampleUserId00000002&action=member.remove" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/audit-events?target_id=SamChenExampleUserId00000002&action=member.remove" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/audit-events" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "target_id": "SamChenExampleUserId00000002", "action": "member.remove", },)response.raise_for_status(){ "message": "audit events retrieved", "audit_events": [ { "id": "ad170000-0000-4000-8000-000000000703", "occurred_at": "2026-11-10T15:00:00Z", "last_occurred_at": "2026-11-10T15:00:00Z", "occurrences": 1, "actor_kind": "workspace_key", "actor_id": "4b1d0000-0000-4000-8000-000000000805", "actor_desc": null, "credential_kind": "workspace_key", "credential_id": "4b1d0000-0000-4000-8000-000000000805", "action": "member.remove", "privileges": [ "member.manage" ], "target_kind": "member", "target_id": "SamChenExampleUserId00000002", "target_desc": null, "org_ids": [ "0a9e0000-0000-4000-8000-000000000101", "0a9e0000-0000-4000-8000-000000000105" ], "all_orgs": false, "outcome": "allowed", "reason": null, "details": { "oauth_connections": 1, "pending_codes": 0, "personal_tokens": 1 }, "details_v": 1, "ip": "203.0.113.24", "user_agent": "access-sync/1.0", "invocation_method": "direct" } ], "next_cursor": null}The removal is recorded with the action member.remove, and its target_id is the person's user_id.
Its details count the personal tokens and connected apps that were deleted.
The person's own events stay in the log: filter on actor_id with their user_id to list what they did.
What the removal leaves in place
| Left in place | What to do |
|---|---|
| Workspace tokens the person created | They keep working with their own grants. Review them in the app, on the Access tab, and revoke any that should go. |
| Registration tokens and ingest keys the person created | They keep working. Rotate any whose secret the person knew. |
| Invitations the person sent | Delete the ones you no longer want, as in step 4. |
| Organizations the person created | Nothing. |
| The person's entries in the audit log | Nothing. They are kept. |
| The person's SparkLogs account, and their membership of other workspaces | Nothing here: the removal affects this workspace only. |
If a step fails
| Step | Response | Cause and fix |
|---|---|---|
| Any | 403 with cause token_scope | The token's scopes leave out admin:write. |
| 2 | 404 | No such group, or one the token cannot see. |
| 3 | 403 APP_API_ERR_BEYOND_OWN_AUTHORITY | The person holds access beyond the token's: a grant with other_orgs or inherited set, an entry with other_grants set, or a group whose grants reach past the token's organizations. Use a token with wider access, or remove the person in the app. A person who is Administrator over every organization always gets this response. |
| 3 | 404 | The person is not a member, is not one the token can see, or is already removed. |
A token refused with that 403 can still delete the person's direct grants inside its own reach. The person then stays a member, and stays in any group whose grants reach beyond the token: setting that group's members returns 403 as well.
Idempotency (safety of repeated API calls)
Removing a member cannot be undone, and a second removal returns 404. Treat that 404 as done. To bring the person back, invite them again.
What the API does not do
- It does not remove a member who holds Administrator over every organization. An administrator does that in the app.
- It does not revoke workspace tokens. The ones the person created keep working until an administrator revokes them in the app.
- It does not delete the person's SparkLogs account or remove them from other workspaces.