Example Use Cases
Each example use case is shown one API call at a time, with every request and response. Each lists the token, role and scopes it needs, what to do when a step fails, and whether its calls are safe to repeat.
| Example | Use it when |
|---|---|
| Sync organizations with a PSA | Client names, ids and structure in SparkLogs should match your PSA without anyone retyping them. |
| Give a client IT administrator access | A co-managed client's own IT administrator should manage only that client's organization. |
| Give a technician access to some clients | A technician joins a team and should see only that team's clients. |
| Offboard a technician | A technician leaves, and their access, tokens and connected apps should be removed. |
| Onboard a client | A company is added in your PSA, and you want its organization and sites created before its devices register. |
| Add a log source for a client | A firewall, server or application should send logs for a client. |
| Offboard a client | A client leaves, and its agents, access and organizations should be removed. |
| Pull agent collection health into a dashboard | An agent that stops reporting or collecting should show on a dashboard or raise a ticket. |
| Fetch latest agent installer | Your own tooling or your RMM script should look up the current agent installer, its hash and its install command. |
| Rotate credentials on a schedule | Your policy requires secrets to be replaced on a schedule. |
| Prepare for an audit | A client or auditor asks who can reach their data and what was done. |
Two smaller examples
Move a device to the right client.
Find it with list agents, filtered by the organization it is in now and by reported_hostname, then move it to the right organization.
The filter ignores case and returns every agent that reports that name, which can be more than one.
The token needs fleet:write.
Retire a device your RMM reports as decommissioned.
Find it with list agents as above, then delete it with uninstall=immediately.
Every example uses one made-up MSP, Northwind IT Services, and its clients. An id on one page is the same object on every other page.