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 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
/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=casey.nguyen%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=casey.nguyen%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": "casey.nguyen@example.com", },)response.raise_for_status(){ "message": "members retrieved", "members": [], "next_cursor": null}/workspaces/{workspace_id}/invitations 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/invitations?email=casey.nguyen%40example.com" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations?email=casey.nguyen%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/invitations" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "email": "casey.nguyen@example.com", },)response.raise_for_status(){ "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_atis null, its email never went out. To send the email, send the invitation with itsid. Each send is another email, and sets the invitation to expire 90 days later. - Neither: go on to step 2.
2. Invite them
/workspaces/{workspace_id}/invitations Scope: admin:write
This example's token carries: workspace:readevents:queryevents:readdevices:readadmin:write
- curl
- PowerShell
- Python
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" }'$body = @{ 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"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "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.raise_for_status(){ "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.
/workspaces/{workspace_id}/invitations/{id}/send Scope: admin:write
This example's token carries: workspace:readevents:queryevents:readdevices:readadmin:write
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations/1a7e0000-0000-4000-8000-000000000601/send" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/invitations/1a7e0000-0000-4000-8000-000000000601/send" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "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.
/workspaces/{workspace_id}/members Scope: any of admin:readadmin:write
Filter by email, and poll until the person is listed with a user_id.
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/members?email=casey.nguyen%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": "casey.nguyen@example.com", },)response.raise_for_status(){ "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.
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401" ` -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/9a0b0000-0000-4000-8000-000000000401" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "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" } ] }}/workspaces/{workspace_id}/groups/{id}/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.
- curl
- PowerShell
- Python
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" ] }'$body = @{ user_ids = @( "SamChenExampleUserId00000002", "CaseyNguyenExampleUserId0003" )}Invoke-RestMethod -Method Put ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401/members" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.put( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401/members" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "user_ids": [ "SamChenExampleUserId00000002", "CaseyNguyenExampleUserId0003", ], },)response.raise_for_status(){ "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:
- curl
- PowerShell
- Python
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" ] }'$body = @{ 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" )}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "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.raise_for_status(){ "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
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/groups/9a0b0000-0000-4000-8000-000000000401" ` -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/9a0b0000-0000-4000-8000-000000000401" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "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
| 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.