# 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
  - A [workspace](https://sparklogs.com/docs/api/reference/workspaces.md) holds [organizations](https://sparklogs.com/docs/api/reference/organizations.md), nested as a tree: a client, a site under it, a department under that.
  - [Agents](https://sparklogs.com/docs/api/reference/agents.md), [ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md) and [registration tokens](https://sparklogs.com/docs/api/reference/registration-tokens.md) each belong to one organization.
- Who can reach it
  - A [member](https://sparklogs.com/docs/api/reference/members.md), a [group](https://sparklogs.com/docs/api/reference/groups.md) or a workspace token is given a [grant](https://sparklogs.com/docs/api/reference/grants.md): a role over some organizations.
  - A grant reaches those organizations and everything below them.
- What a token may do
  - Access (its grants, or its owner's) × Scopes (its access limits) = The calls it can make.

## Workspace

A [workspace](https://sparklogs.com/docs/api/reference/workspaces.md) 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](https://sparklogs.com/docs/api/reference/credential.md) 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](https://sparklogs.com/docs/api/reference/organizations.md) 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](https://sparklogs.com/docs/api/reference/agents.md).** 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](https://sparklogs.com/docs/api/reference/ingest-keys.md).** A credential that lets a log shipper, firewall or application send data into the organization.
- **[Registration tokens](https://sparklogs.com/docs/api/reference/registration-tokens.md).** 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](https://sparklogs.com/docs/api/reference/grants.md) gives one [role](https://sparklogs.com/docs/api/reference/roles.md) 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](https://sparklogs.com/docs/api/reference/members.md)** are the people in the workspace. Adding one takes two calls: [create an invitation](https://sparklogs.com/docs/api/reference/invitations.md), which sends nothing, then send its email. The person accepts in the app.
- **[Groups](https://sparklogs.com/docs/api/reference/groups.md)** hold members. One grant to a group covers the whole team.
- **[Roles](https://sparklogs.com/docs/api/reference/roles.md)** are named sets of privileges, such as `organization.read` or `agent.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](https://sparklogs.com/docs/workspace/users-and-roles.md) 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](https://sparklogs.com/docs/api/authentication.md) for the kinds of token and [Scopes](https://sparklogs.com/docs/api/scopes.md) 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](https://sparklogs.com/docs/workspace/audit-logs.md) or through [the API](https://sparklogs.com/docs/api/reference/audit-events.md), where a filter on `credential_id` shows everything one token did.

---

Source: <https://sparklogs.com/docs/api/concepts>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
