Authentication
Send an API token in the Authorization header of every call.
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 lists the kinds it works with.
- 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 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. 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.
{ "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:
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 notok, 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
- 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.
- 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:writecould have added people or grants, and one withfleet:writecould have deleted agents: undo what you find. - Replace what it could read. A token with
fleet:deployorfleet:writecan reveal ingest keys and registration tokens. If the leaked token had either, rotate those too. - 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 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.