Concepts
Every call in the API works on one of the objects below. Each section links to the object's reference page.
What you manage
Who can reach it
- Client
- Site
- Department
What a token may do
Workspace
A workspace is your whole SparkLogs account: for an MSP, the MSP itself.
It lives in one region, and everything else belongs to it.
Every API token belongs to exactly one workspace, and most paths start with /workspaces/{workspace_id}.
To find the workspace id, read the credential with the token.
A change made through the API normally applies in every region at once: the API tells the SparkLogs services in each region to drop what they had cached.
Many write responses carry cache_clear_status, and ok means every region did.
Any other value means some services may act on the earlier state for a time:
- up to 15 minutes for an API token, a grant, a group, a member or a newly created organization;
- up to two hours for an ingest key, an agent, or an organization that was deleted, restored or moved.
Organizations
Organizations form a tree inside the workspace. An MSP usually has one organization per client, and may nest sites or departments under a client.
Three things about organizations matter to an integration:
- Client ids. An organization can record the id your RMM uses for the client (
rmm_client_id) and the id your PSA uses (psa_client_id). You can list organizations by either, which is how a sync finds the organization for a PSA company. Client ids are not unique. A lookup returns every organization you can see with that id, and a separate call checks an id for duplicates before you use it. - Access covers everything below. A role given at an organization also applies to every organization below it.
- A delete can be undone. A deleted organization can be restored, as long as its parent is not deleted. An organization can be deleted only once nothing live is left below it: no organization, agent or ingest key. Registration tokens and grants do not block the delete, and are kept.
What lives at an organization
- Agents. A SparkLogs Agent installed on a device. Each reports its health: when it last checked in, when data last arrived, and whether collection is working.
- Ingest keys. A credential that lets a log shipper, firewall or application send data into the organization.
- Registration tokens. What an agent installer presents to join the workspace. Your RMM deploys the installer with a registration token, and each device then registers itself in the right organization.
An ingest key and a registration token are secrets for sending data in. Neither can call this API.
Agents and ingest keys are separate lists, each with its own calls to rename, move, delete and restore. An agent call refuses the id of an ingest key, and an ingest key call refuses the id of an agent. Deleting an agent also schedules its uninstall from the device. Restoring the record later does not reinstall it.
Your own ids and fields
An agent has two fields for your systems' ids: rmm_device_id and psa_device_id.
The installer can set them, an update call can change them, and the list of agents filters by either.
An organization holds rmm_client_id and psa_client_id in the same way.
An update changes the fields you send and keeps the ones you leave out.
null clears a field, and returns 400 on a field that cannot be empty, such as a name.
Organizations, agents and ingest keys also take custom_fields: an object of up to 50 keys of your own, each value a string, a number or a boolean.
Use it for facts your automation needs beside the record, such as a contract tier or a site code.
Write a key with the record's update call: a key you leave out keeps its value, and null removes it.
custom_fields is returned only when fields names it.
Do not put secrets in custom_fields: anyone who can read the record can read them.
Names, labels, client ids and device ids are stored cleaned. Line breaks and other whitespace become a space, invisible characters are removed, and spaces at either end are removed. A filter cleans its value the same way before matching.
People, groups, roles and grants
Access in SparkLogs is a set of grants. A grant gives one role to one person or group, and covers one of three things:
- every organization, including ones created later, together with the workspace itself;
- a list of organizations, each with everything below it;
- the workspace itself only, for settings that belong to no organization. A grant like this covers no organization.
The other pieces:
- Members are the people in the workspace. Adding one takes two calls: create an invitation, which sends nothing, then send its email. The person accepts in the app.
- Groups hold members. One grant to a group covers the whole team.
- Roles are named sets of privileges, such as
organization.readoragent.write. The API lists the standard roles and your custom ones. It does not change them.
To let a technician see three clients and nothing else, give them (or their group) a role at those three organizations. See Users, groups and roles for the same model in the app.
API tokens
A token is what your automation presents to call the API. There are two kinds you create, both in the app:
- A personal token acts as the person who created it. It can never do more than that person can, and it can be limited to a narrower role and to fewer organizations.
- A workspace token belongs to the workspace, not a person. It has grants of its own and keeps working when people leave. A workspace token cannot change its own grants.
What a token can do is decided in layers. The access behind it decides which organizations and objects it can reach. Its scopes limit which kinds of call it may make. A call succeeds only when every layer allows it. See Authentication for the kinds of token and Scopes for the limits.
Words used on these pages
| Word | Meaning |
|---|---|
| Privilege | One thing a caller may do, such as organization.create. |
| Role | A named set of privileges. |
| Grant | A role given to a person, group or workspace token over some organizations or the workspace. |
| Reach | The organizations a grant covers: the ones it names and everything below them. |
| Access | Everything a person or token can do through all its grants. |
| Scope | A cap on an API token. It names kinds of call the token may make. It never adds access. |
| Connected app | An AI assistant or other app a person approved to act for them, with an OAuth token. |
One word is used twice in the data: a grant has a field named scope, which is its reach.
It has nothing to do with a token's scopes.
The audit log
Changes made through the API are recorded in the workspace's audit log, whether they succeed or are refused. Reads of secrets are recorded too, and so is any read refused for lack of access. An entry made with a workspace token names the token. An entry made with a personal token or a connected app names the person and the credential. A call refused for going over a rate limit, or made with a token the API does not recognize, is not recorded.
You can read the log in the app or through the API, where a filter on credential_id shows everything one token did.