Skip to main content

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 tokenWith the scope
Organization Administrator at an organization above every client the person can reachno 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​

GET/workspaces/{workspace_id}/members
List members

Scope: any of admin:readadmin:write

Filter by email.

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

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 email filter, 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​

GET/workspaces/{workspace_id}/groups
List groups

Scope: any of admin:readadmin:write

Pass fields with members added to the default fields.

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

DELETE/workspaces/{workspace_id}/members/{user_id}
Remove a member

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/members/SamChenExampleUserId00000002" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "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​

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?email=sam.chen%40example.com" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "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​

GET/workspaces/{workspace_id}/audit-events
List audit events

Scope: any of admin:readadmin:write

Request
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"
Response 200
{  "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 placeWhat to do
Workspace tokens the person createdThey 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 createdThey keep working. Rotate any whose secret the person knew.
Invitations the person sentDelete the ones you no longer want, as in step 4.
Organizations the person createdNothing.
The person's entries in the audit logNothing. They are kept.
The person's SparkLogs account, and their membership of other workspacesNothing here: the removal affects this workspace only.

If a step fails​

StepResponseCause and fix
Any403 with cause token_scopeThe token's scopes leave out admin:write.
2404No such group, or one the token cannot see.
3403 APP_API_ERR_BEYOND_OWN_AUTHORITYThe 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.
3404The 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.