# 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

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

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

Filter by `email`.

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

```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
}
```

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](https://sparklogs.com/docs/api/reference/invitations.md#list-invitations) with the same `email` filter, then [delete the invitation](https://sparklogs.com/docs/api/reference/invitations.md#delete-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](https://sparklogs.com/docs/api/reference/groups.md#list-groups)

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

Pass `fields` with `members` added to the default fields.

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

```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,
      "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](https://sparklogs.com/docs/api/reference/members.md#delete-member)

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/members/SamChenExampleUserId00000002" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "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](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?email=sam.chen%40example.com" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "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](https://sparklogs.com/docs/api/reference/invitations.md#delete-invitation) any you no longer want.

### 5. Check the audit log

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

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

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

```json
{
  "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](https://sparklogs.com/docs/api/use-cases/rotate-credentials.md) 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](https://sparklogs.com/docs/api/reference/grants.md#delete-grant) 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.

---

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