# Authentication

Send an API token in the `Authorization` header of every call.

```bash
curl "https://engine.sparklogs.app/app-api/credential" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

A token begins with `sl_` and belongs to one workspace.

## Kinds of credential

Each call in the [reference](https://sparklogs.com/docs/api/reference.md) lists the kinds it works with.

| Kind | Value of `kind` | What it is |
| - | - | - |
| Signed-in person | `session` | A person signed in to the SparkLogs app, with the access their grants give. |
| Personal token | `user_key` | A personal token, acting as the person who created it, inside the scopes and organizations it was limited to. |
| OAuth token | `oauth` | An OAuth token, acting as the person who approved the connected app, inside the scopes they approved. |
| Workspace token | `workspace_key` | A workspace token, belonging to the workspace rather than a person, with the access of its own grants. |

An integration that should outlive any one person's account uses a workspace token.
A personal token suits automation that one engineer runs as themselves.

## Create a token

Create tokens in the app.
The API has no call that creates one.
Open **Workspace Settings**, then **Access**, and under **API tokens** choose **New Token**.
See [Access](https://sparklogs.com/docs/workspace/access.md) for each step.

The dialog asks for:

- **Name.** What the token is for. It appears in the audit log.
- **Owner.** **You** makes a personal token. **This workspace** makes a workspace token, and is offered to Administrators and Organization Administrators.
- **Permissions**, for a personal token: everything you can do, a narrower role, or custom permissions. For a workspace token, **Access**: one or more grants, each a role over some organizations.
- **Access limits.** These are the token's [scopes](https://sparklogs.com/docs/api/scopes.md). With no limit, the token carries every scope. To limit it, tick the box and choose the few scopes your automation needs.
- **Authorized organizations**, for a personal token that should reach fewer clients than you do.
- **Expires.** 365 days unless you choose another period or **Never**.

The secret is shown once.
Store it where your automation reads secrets from, such as your RMM's or PSA's credential store or a secrets manager.

## Where to call the API from

Call the API from a server, a scheduled task or your own machine.
Do not put a token in a web page or a desktop app that you hand to others: anyone who can read it can use it.

## When a token is refused

A call returns 401 when the token is missing or malformed, unknown, revoked, deleted or expired.
It also returns 401 when a personal token's owner is no longer a member of the workspace.

When one network address keeps sending tokens that do not work, calls from that address that present an API token can be refused with 429, a valid token included.
`cause` is `invalid_token_attempts`.
An automation that loops on a revoked token therefore sees mostly 429, not 401.
Fix the token; retrying does not help.
Once the failing calls stop, the 429 clears within seconds.
Until then, other integrations calling from the same address can be refused too.

Response (401)

```json
{
  "error": "the API token is not valid",
  "error_code": "APP_API_ERR_UNAUTHORIZED"
}
```

If a token stops working, look at its **Status** in the list under **API tokens** first: Active, Revoked, Expired or Deleted.

## Rotate a token

A personal token or a workspace token can replace its own secret:

```bash
curl -X POST "https://engine.sparklogs.app/app-api/credential/rotate" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

The response carries the new secret in `token`, once.
The old secret stops working on this API at that moment.
The token's id, name, scopes, access and expiry do not change.

Two cautions:

- **Never retry a rotation.** If the response is lost, the new secret is lost with it and the token is locked out. A second attempt with the old secret returns 401. Rotate the token or create a new one in the app.
- **Check `cache_clear_status`.** It says whether every region has dropped the old secret. If it is not `ok`, other SparkLogs services can keep accepting the old secret for up to 15 minutes.

Anyone who holds a token's secret can rotate it. The rightful holder is then locked out.
The rotation is recorded in the audit log with the caller's IP address.
If a token was rotated and you did not do it, revoke it.

## Revoke a token

Revoke a token in the app, under **API tokens** on the **Access** tab.
You can revoke your own personal tokens.
Revoking another person's token or a workspace token takes the Administrator or Organization Administrator role.
**Revoke** keeps the token listed, marked Revoked. **Delete** removes it.

A revoked token returns 401 on its next call to this API.
That holds even when someone else has rotated its secret since.
The other SparkLogs services usually refuse it at once as well, and always within 15 minutes.

The API cannot create or revoke tokens, because no scope carries those privileges. A leaked token cannot make more tokens.
One call does remove tokens as a side effect: removing a member deletes that person's personal tokens and connected apps in the workspace.

## If a token leaks

1. **Revoke it in the app.** This API refuses it from its next call, even if whoever holds it has rotated the secret. The other SparkLogs services, which answer AI assistants and queries, usually refuse it at once as well, and always within 15 minutes.
2. **See what it did.** In the audit log, filter by the token to list every call it made and from which address. A token with `admin:write` could have added people or grants, and one with `fleet:write` could have deleted agents: undo what you find.
3. **Replace what it could read.** A token with `fleet:deploy` or `fleet:write` can reveal ingest keys and registration tokens. If the leaked token had either, [rotate those](https://sparklogs.com/docs/api/use-cases/rotate-credentials.md) too.
4. **Create a new token** with only the scopes it needs, and store it somewhere the old one was not.

The integration is down from step 1 until step 4.
Revoke first. Creating the replacement takes a minute in the app.

Rotating a leaked token yourself locks out everyone else who holds it. Whoever rotates first keeps the token.
Revoking works in either case.

## Check what a token is

[Read the credential](https://sparklogs.com/docs/api/reference/credential.md) to learn a token's kind, id, workspace, region and scopes.
A token with no access limits lists every scope.
An automation with a workspace token makes this call first, to find its workspace id.

---

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