# Give a Technician Access to Some Clients

A new technician should see the clients they work on and no others.
This example shows how to invite them and give them a role at a chosen set of client organizations.
It uses a group. Adding the next technician to the same team is then a single call.

We recommend grouping clients under a parent organization and giving your own staff access there.
Access at single clients is for narrower cases, such as co-managed IT, where a client's own IT administrators need access to their organization and no other.
For that case, see [Give a client IT administrator access](https://sparklogs.com/docs/api/use-cases/grant-client-admin-access.md).

## What the token needs

| Give a workspace token | With the scope |
| - | - |
| **Organization Administrator** at an organization above the clients involved | no access limits |

A token can only give access that it holds itself, and its scopes limit that too.
Giving a role takes every scope that role's privileges fall under, so `admin:write` alone cannot give a role that reads events or changes agents.
A grant refused only because the token lacks a scope returns 403 with `cause` `token_scope`, and `required_scope` names the scope.
A grant that reaches beyond the token's own access returns 403 `APP_API_ERR_BEYOND_OWN_AUTHORITY`.
The simplest token for this has no access limits.
If you do limit it, give it every scope that the roles it gives fall under.

## Steps

### 1. See whether the person is already a member

**`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=casey.nguyen%40example.com" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "members retrieved",
  "members": [],
  "next_cursor": null
}
```

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

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/invitations?email=casey.nguyen%40example.com" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "invitations retrieved",
  "invitations": [],
  "next_cursor": null
}
```

Members and pending invitations are separate lists.
The `email` filter matches exactly, ignoring case.

- The person is a member: skip to step 4.
- The person has a pending invitation: do not create another. If its `last_sent_at` is null, its email never went out. To send the email, [send the invitation](https://sparklogs.com/docs/api/reference/invitations.md#send-invitation) with its `id`. Each send is another email, and sets the invitation to expire 90 days later.
- Neither: go on to step 2.

### 2. Invite them

**`POST /workspaces/{workspace_id}/invitations`** [Invite a person](https://sparklogs.com/docs/api/reference/invitations.md#create-invitation)

Scope: `admin:write`

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

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "casey.nguyen@example.com",
    "grants": [
      {
        "role_id": "analyst",
        "scope": {
          "kind": "selected",
          "org_ids": [
            "0a9e0000-0000-4000-8000-000000000103"
          ]
        }
      }
    ],
    "invitation_id": "1a7e0000-0000-4000-8000-000000000601"
  }'
```

Response (200)

```json
{
  "message": "invitation saved",
  "id": "1a7e0000-0000-4000-8000-000000000601"
}
```

Send the email address and the grants the person should start with: a role and the organizations it covers.
Creating the invitation sends nothing yet.

Choose the `invitation_id` yourself and keep it.
Sending the same id again updates that invitation, which makes a retry safe.
A different id for an email that already has a pending invitation returns 409.

**`POST /workspaces/{workspace_id}/invitations/{id}/send`** [Send an invitation email](https://sparklogs.com/docs/api/reference/invitations.md#send-invitation)

Scope: `admin:write`

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

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations/1a7e0000-0000-4000-8000-000000000601/send" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "sent invitation"
}
```

This sends the email.
A token can send 500 invitation emails in five minutes.

### 3. Wait for them to accept

The person follows the link and accepts in the app.
An invitation can be accepted only in the app.

**`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`, and poll until the person is listed with a `user_id`.

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members?email=casey.nguyen%40example.com" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "members retrieved",
  "members": [
    {
      "user_id": "CaseyNguyenExampleUserId0003",
      "email": "casey.nguyen@example.com",
      "full_name": "Casey Nguyen",
      "display_name": "Casey",
      "is_self": false,
      "created_at": "2026-11-08T11:00:00Z",
      "deleted_at": null,
      "grants": [
        {
          "id": "6a170000-0000-4000-8000-000000000506",
          "role_id": "analyst",
          "scope": {
            "kind": "selected",
            "org_ids": [
              "0a9e0000-0000-4000-8000-000000000103"
            ],
            "inherited": false,
            "other_orgs": false
          }
        }
      ],
      "other_grants": false,
      "groups": []
    }
  ],
  "next_cursor": null
}
```

Poll every five minutes.
Decide how long to wait for the person to accept, a day or two for example, and then stop.
If you stop, run the steps again later: step 1 finds the person as a member or as a pending invitation.

A token with access to only part of the tree sees a member only when the member has a grant inside that part, either their own or through a group.
Give the invitation at least one grant inside that part, or the person never appears in this list.

### 4. Put them in a group that holds the access

If the team's group exists, add the person to it.
Setting a group's members replaces the whole list. Read the list first.
The token must cover every role the group's grants give, as in [What the token needs](#what-the-token-needs).

**`GET /workspaces/{workspace_id}/groups/{id}`** [Read a group](https://sparklogs.com/docs/api/reference/groups.md#read-group)

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

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

Response (200)

```json
{
  "message": "workspace group retrieved",
  "group": {
    "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"
      }
    ]
  }
}
```

**`PUT /workspaces/{workspace_id}/groups/{id}/members`** [Set a group's members](https://sparklogs.com/docs/api/reference/groups.md#update-group-members)

Scope: `admin:write`

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

Send every member's `user_id`, the existing ones and the new one.

```bash
curl -X PUT \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401/members" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": [
      "SamChenExampleUserId00000002",
      "CaseyNguyenExampleUserId0003"
    ]
  }'
```

Response (200)

```json
{
  "message": "group members replaced",
  "id": "9a0b0000-0000-4000-8000-000000000401",
  "cache_clear_status": "ok"
}
```

If there is no group yet, create it with its grants and its first members in one call:

**`POST /workspaces/{workspace_id}/groups`** [Create a group](https://sparklogs.com/docs/api/reference/groups.md#create-group)

Scope: `admin:write`

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "grants": [
      {
        "role_id": "analyst_no_raw_logs",
        "scope": {
          "kind": "selected",
          "org_ids": [
            "0a9e0000-0000-4000-8000-000000000101",
            "0a9e0000-0000-4000-8000-000000000105"
          ]
        }
      }
    ],
    "name": "Helpdesk Tier 1",
    "user_ids": [
      "SamChenExampleUserId00000002"
    ]
  }'
```

Response (200)

```json
{
  "message": "group created",
  "id": "9a0b0000-0000-4000-8000-000000000401",
  "cache_clear_status": "ok"
}
```

A grant names a role and where it applies.
Read the available roles and their ids from [the list of roles](https://sparklogs.com/docs/api/reference/roles.md).
For a set of clients, the grant covers a list of organizations, each with everything below it.

### 5. Check the result

**`GET /workspaces/{workspace_id}/groups/{id}`** [Read a group](https://sparklogs.com/docs/api/reference/groups.md#read-group)

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

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

Response (200)

```json
{
  "message": "workspace group retrieved",
  "group": {
    "id": "9a0b0000-0000-4000-8000-000000000401",
    "name": "Helpdesk Tier 1",
    "created_at": "2026-11-02T10:00:00Z",
    "updated_at": "2026-11-08T12: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": 2,
    "members": [
      {
        "user_id": "SamChenExampleUserId00000002",
        "email": "sam.chen@example.com",
        "full_name": "Sam Chen",
        "display_name": "Sam"
      },
      {
        "user_id": "CaseyNguyenExampleUserId0003",
        "email": "casey.nguyen@example.com",
        "full_name": "Casey Nguyen",
        "display_name": "Casey"
      }
    ]
  }
}
```

The response lists the group's grants and its members.
The technician can confirm their own access by calling [read your access](https://sparklogs.com/docs/api/reference/access.md) with a token of their own.

## Without a group

To give one person a role directly, [create a grant](https://sparklogs.com/docs/api/reference/grants.md#create-grant) with the person as the grantee.
A group is easier to review later: it lists in one place who is on the team and what the team can reach.

## Take access away

- Remove the person from the group by setting its members without them.
- [Delete a grant](https://sparklogs.com/docs/api/reference/grants.md#delete-grant) given to them directly.
- Remove the member when they leave the company. [Offboard a technician](https://sparklogs.com/docs/api/use-cases/offboard-technician.md) covers what that removes and what it leaves in place.

## If a step fails

| Call | Response | Cause and fix |
| - | - | - |
| Create an invitation | 409 `APP_API_ERR_INVITATION_EMAIL_TAKEN` | The email already belongs to a member or to another pending invitation. |
| Create an invitation | 400 `APP_API_ERR_MISSING_PARAMETER` | `grants` was left out. Send a list. |
| Create an invitation | 403 `APP_API_ERR_BEYOND_OWN_AUTHORITY` | The list of grants is empty and the token reaches only part of the tree. Include at least one grant. |
| Any grant | 403 `APP_API_ERR_BEYOND_OWN_AUTHORITY` | The grant reaches beyond the token's own access. |
| Create a group | 409 `APP_API_ERR_ALREADY_TAKEN` | The name is taken. If this is a retry, your first attempt may have worked: list the groups with `name` to check. |
| Send an invitation | 429 with `cause` `send_limit` | Over the sending limit. Wait the seconds in `Retry-After`. |

## What the API does not do

- An invitation cannot place the person in a group. Add them once they have accepted.
- No call shows another person's combined access from all their grants and groups. Read the member's own grants and each group's grants.
- Two integrations setting one group's members at the same moment can overwrite each other. Let only one system set a group's members.

---

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