Rotate Credentials on a Schedule
Three kinds of secret can be replaced through the API, and each works differently.
| Secret | How it is replaced | Overlap between old and new |
|---|---|---|
| An API token's own secret | The token rotates itself. | None. This API refuses the old secret at once. |
| An ingest key | One call replaces it. | None by design. Senders need the new key at once. |
| A registration token | Create a new one, then revoke the old one. | You choose: both work until you revoke the old one. |
Rotate the API token your automation uses
A personal token or a workspace token can replace its own secret. It needs no scope and no privilege to do so.
/credential/rotate This example's token carries: workspace:readfleet:deploy
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/credential/rotate" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/credential/rotate" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/credential/rotate" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "token rotated", "credential_id": "4b1d0000-0000-4000-8000-000000000803", "token": "sl_us_EXAMPLE_NOT_A_REAL_TOKEN", "workspace_id": "5e1f0a00-0000-4000-8000-000000000001", "user_id": null, "label": "RMM deployment", "scope_restriction": "listed", "scopes": [ "workspace:read", "fleet:deploy" ], "expires_at": "2027-11-10T09:00:00Z", "cache_clear_by_region": { "us-central": "ok" }, "cache_clear_status": "ok"}- Make the call above with the current secret.
- Write
tokenfrom the response to your secret store before doing anything else. It is sent once. - Call read the credential with the new secret to confirm it works.
/credential This example's token carries: workspace:readfleet:deploy
Made with the new secret.
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/credential" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/credential" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/credential" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "credential": { "kind": "workspace_key", "credential_id": "4b1d0000-0000-4000-8000-000000000803", "workspace_id": "5e1f0a00-0000-4000-8000-000000000001", "region_id": "us-central", "scope_restriction": "listed", "scopes": [ "workspace:read", "fleet:deploy" ], "expires_at": "2027-11-10T09:00:00Z" }, "message": "credential retrieved"}The token keeps its id, name, scopes, access and expiry.
Rotation does not move the expiry date: a token created to last 365 days still ends on the same day.
Read the credential returns expires_at, so your automation can warn a person ahead of that date to replace the token in the app.
Do not retry a rotation. If the response is lost, the new secret is lost with it, and the old one no longer works. A second attempt with the old secret returns 401. Recovery needs a person: in the app, on the Access tab, rotate the token or create a new one.
So keep the rotation step simple: put no retry around it, and write to the secret store immediately after it.
Rotate an ingest key
Find the key, then replace its secret.
/workspaces/{workspace_id}/ingest-keys Scope: workspace:read
Filter by organization_id and name. Names are not unique, so check every key the list returns.
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys?organization_id=0a9e0000-0000-4000-8000-000000000105&name=harbor%20dental%20servers" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys?organization_id=0a9e0000-0000-4000-8000-000000000105&name=harbor%20dental%20servers" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "organization_id": "0a9e0000-0000-4000-8000-000000000105", "name": "harbor dental servers", },)response.raise_for_status(){ "as_of": "2026-11-10T15:05:00Z", "ingest_keys": [ { "id": "a9e70000-0000-4000-8000-000000000204", "workspace_id": "5e1f0a00-0000-4000-8000-000000000001", "name": "Harbor Dental servers", "description": null, "organization_id": "0a9e0000-0000-4000-8000-000000000105", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000105", "a9e70000-0000-4000-8000-000000000204" ], "data_status": "online", "last_data_at": "2026-11-10T14:00:00Z", "created_at": "2026-11-05T08:00:00Z", "updated_at": "2026-11-10T14:00:00Z", "deleted_at": null, "organization_deleted_at": null } ], "message": "ingest keys retrieved", "next_cursor": null}/workspaces/{workspace_id}/ingest-keys/{id}/rotate Scope: any of fleet:deployfleet:write
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204/rotate" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204/rotate" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204/rotate" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "key replaced", "key": "EXAMPLE-NEW-INGEST-KEY-NOT-A-REAL-SECRET", "cache_clear_status": "ok"}The response carries the new secret in key.
The old key is refused at once when cache_clear_status in the response is ok, so update every sender right after the call.
Otherwise the old key can keep working for up to two hours.
If the response is lost, do not rotate again: that would replace the key a second time. Read the ingest key's secret instead.
A deleted ingest key returns 409 APP_API_ERR_CONFLICT to both calls.
Restore it first.
A SparkLogs Agent manages its own credential, and no call rotates it.
Replace a registration token
A registration token's secret cannot be changed in place.
- Create a new registration token at the same organization, with an
expires_at. - Change your RMM's install command to the new token.
- Revoke the old one. To find its id, list the organization's registration tokens with
status=activeand match the label. - Read the new token and watch
use_countandlast_used_atto confirm installs are using it.
Devices that registered with the old token keep working.
/workspaces/{workspace_id}/registration-tokens Scope: any of fleet:deployfleet:write
Find the token to replace: active, at the organization, with your label.
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens?organization_id=0a9e0000-0000-4000-8000-000000000101&status=active&label=Lakeside%20Clinic%20rollout" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens?organization_id=0a9e0000-0000-4000-8000-000000000101&status=active&label=Lakeside%20Clinic%20rollout" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "organization_id": "0a9e0000-0000-4000-8000-000000000101", "status": "active", "label": "Lakeside Clinic rollout", },)response.raise_for_status(){ "as_of": "2026-11-10T09:01:00Z", "message": "registration tokens retrieved", "next_cursor": null, "registration_tokens": [ { "id": "7e0c0000-0000-4000-8000-000000000301", "organization_id": "0a9e0000-0000-4000-8000-000000000101", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000101", "7e0c0000-0000-4000-8000-000000000301" ], "label": "Lakeside Clinic rollout", "status": "active", "created_by_user_id": "AlexRiveraExampleUserId00001", "expires_at": "2026-11-30T00:00:00Z", "revoked_at": null, "revocation_reason": null, "use_count": 1, "last_used_at": "2026-11-03T12:00:00Z", "created_at": "2026-11-03T11:00:00Z", "updated_at": "2026-11-03T12:00:00Z", "deleted_at": null } ], "watermark": "2026-11-10T09:00:00Z"}/workspaces/{workspace_id}/registration-tokens Scope: any of fleet:deployfleet:write
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "expires_at": "2026-12-30T00:00:00Z", "label": "Lakeside Clinic rollout, December", "organization_id": "0a9e0000-0000-4000-8000-000000000101" }'$body = @{ expires_at = "2026-12-30T00:00:00Z" label = "Lakeside Clinic rollout, December" organization_id = "0a9e0000-0000-4000-8000-000000000101"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "expires_at": "2026-12-30T00:00:00Z", "label": "Lakeside Clinic rollout, December", "organization_id": "0a9e0000-0000-4000-8000-000000000101", },)response.raise_for_status(){ "message": "registration token created", "id": "7e0c0000-0000-4000-8000-000000000302", "token": "EXAMPLE-NEW-REGISTRATION-TOKEN-NOT-REAL"}/workspaces/{workspace_id}/registration-tokens/{id}/revoke Scope: any of fleet:deployfleet:write
- curl
- PowerShell
- Python
curl -X POST \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/revoke" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "reason": "Replaced by a newer token" }'$body = @{ reason = "Replaced by a newer token"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/revoke" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/revoke" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "reason": "Replaced by a newer token", },)response.raise_for_status(){ "message": "registration token revoked"}/workspaces/{workspace_id}/registration-tokens/{id} Scope: any of fleet:deployfleet:write
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000302" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000302" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000302" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "message": "registration token retrieved", "registration_token": { "id": "7e0c0000-0000-4000-8000-000000000302", "organization_id": "0a9e0000-0000-4000-8000-000000000101", "path": [ "0a9e0000-0000-4000-8000-000000000100", "0a9e0000-0000-4000-8000-000000000101", "7e0c0000-0000-4000-8000-000000000302" ], "label": "Lakeside Clinic rollout, December", "status": "active", "created_by_user_id": null, "expires_at": "2026-12-30T00:00:00Z", "revoked_at": null, "revocation_reason": null, "use_count": 0, "last_used_at": null, "created_at": "2026-11-10T11:00:00Z", "updated_at": "2026-11-10T11:00:00Z", "deleted_at": null }}What the token needs
| To rotate | Scope | Privilege held at |
|---|---|---|
| Its own secret | none | nothing |
| Ingest keys | fleet:deploy | the key's organization |
| Registration tokens | fleet:deploy | the token's organization |
The Deployment Manager role holds both.
What the API does not do
- A token cannot extend its own expiry or create its replacement. A person does that in the app.
- An API token or an ingest key never has two valid values by design. When
cache_clear_statusin a response is notok, other SparkLogs services can still accept the old value: for up to 15 minutes for an API token and up to two hours for an ingest key. This API always refuses an old token secret at once.