Skip to main content

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.

What the token needs​

Give a workspace tokenWith the scope
Organization Administrator at an organization above the clients involvedno 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

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=casey.nguyen%40example.com" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "message": "members retrieved",  "members": [],  "next_cursor": null}
GET/workspaces/{workspace_id}/invitations
List invitations

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

Scope: admin:write

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

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

Scope: admin:write

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

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

Scope: any of admin:readadmin:write

Filter by email, and poll until the person is listed with a user_id.

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

GET/workspaces/{workspace_id}/groups/{id}
Read a group

Scope: any of admin:readadmin:write

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

Scope: admin:write

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

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

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

Scope: admin:write

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

Scope: any of admin:readadmin:write

Request
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
{  "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 with a token of their own.

Without a group​

To give one person a role directly, create a 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 given to them directly.
  • Remove the member when they leave the company. Offboard a technician covers what that removes and what it leaves in place.

If a step fails​

CallResponseCause and fix
Create an invitation409 APP_API_ERR_INVITATION_EMAIL_TAKENThe email already belongs to a member or to another pending invitation.
Create an invitation400 APP_API_ERR_MISSING_PARAMETERgrants was left out. Send a list.
Create an invitation403 APP_API_ERR_BEYOND_OWN_AUTHORITYThe list of grants is empty and the token reaches only part of the tree. Include at least one grant.
Any grant403 APP_API_ERR_BEYOND_OWN_AUTHORITYThe grant reaches beyond the token's own access.
Create a group409 APP_API_ERR_ALREADY_TAKENThe name is taken. If this is a retry, your first attempt may have worked: list the groups with name to check.
Send an invitation429 with cause send_limitOver 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.