Skip to main content

Rotate Credentials on a Schedule

Three kinds of secret can be replaced through the API, and each works differently.

SecretHow it is replacedOverlap between old and new
An API token's own secretThe token rotates itself.None. This API refuses the old secret at once.
An ingest keyOne call replaces it.None by design. Senders need the new key at once.
A registration tokenCreate 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.

POST/credential/rotate
Rotate the credential's secret

This example's token carries: workspace:readfleet:deploy

Request
curl -X POST \  "https://engine.sparklogs.app/app-api/credential/rotate" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
Cache-Control: no-store
{  "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"}
  1. Make the call above with the current secret.
  2. Write token from the response to your secret store before doing anything else. It is sent once.
  3. Call read the credential with the new secret to confirm it works.
GET/credential
Read credential metadata

This example's token carries: workspace:readfleet:deploy

Made with the new secret.

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/credential" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "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.

GET/workspaces/{workspace_id}/ingest-keys
List ingest keys

Scope: workspace:read

Filter by organization_id and name. Names are not unique, so check every key the list returns.

Request
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"
Response 200
{  "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}
POST/workspaces/{workspace_id}/ingest-keys/{id}/rotate
Replace an ingest key's secret

Scope: any of fleet:deployfleet:write

Request
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"
Response 200
Cache-Control: no-store
{  "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.

  1. Create a new registration token at the same organization, with an expires_at.
  2. Change your RMM's install command to the new token.
  3. Revoke the old one. To find its id, list the organization's registration tokens with status=active and match the label.
  4. Read the new token and watch use_count and last_used_at to confirm installs are using it.

Devices that registered with the old token keep working.

GET/workspaces/{workspace_id}/registration-tokens
List registration tokens

Scope: any of fleet:deployfleet:write

Find the token to replace: active, at the organization, with your label.

Request
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"
Response 200
{  "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"}
POST/workspaces/{workspace_id}/registration-tokens
Create a registration token

Scope: any of fleet:deployfleet:write

Request
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"  }'
Response 200
Cache-Control: no-store
{  "message": "registration token created",  "id": "7e0c0000-0000-4000-8000-000000000302",  "token": "EXAMPLE-NEW-REGISTRATION-TOKEN-NOT-REAL"}
POST/workspaces/{workspace_id}/registration-tokens/{id}/revoke
Revoke a registration token

Scope: any of fleet:deployfleet:write

Request
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"  }'
Response 200
{  "message": "registration token revoked"}
GET/workspaces/{workspace_id}/registration-tokens/{id}
Read a registration token

Scope: any of fleet:deployfleet:write

Request
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"
Response 200
{  "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 rotateScopePrivilege held at
Its own secretnonenothing
Ingest keysfleet:deploythe key's organization
Registration tokensfleet:deploythe 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_status in a response is not ok, 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.