# 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.

**`POST /credential/rotate`** [Rotate the credential's secret](https://sparklogs.com/docs/api/reference/credential.md#rotate-credential)

This example's token carries: `workspace:read`, `fleet:deploy`

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

Response (200)

Headers: `Cache-Control: no-store`

```json
{
  "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](https://sparklogs.com/docs/api/reference/credential.md) with the new secret to confirm it works.

**`GET /credential`** [Read credential metadata](https://sparklogs.com/docs/api/reference/credential.md#read-credential)

This example's token carries: `workspace:read`, `fleet:deploy`

Made with the new secret.

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

Response (200)

```json
{
  "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](https://sparklogs.com/docs/api/reference/credential.md) 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](https://sparklogs.com/docs/api/reference/ingest-keys.md#list-ingest-keys)

Scope: `workspace:read`

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

```bash
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)

```json
{
  "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](https://sparklogs.com/docs/api/reference/ingest-keys.md#rotate-ingest-key)

Scope: any of `fleet:deploy`, `fleet:write`

```bash
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)

Headers: `Cache-Control: no-store`

```json
{
  "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](https://sparklogs.com/docs/api/reference/ingest-keys.md#reveal-ingest-key) instead.

A deleted ingest key returns 409 `APP_API_ERR_CONFLICT` to both calls.
[Restore it](https://sparklogs.com/docs/api/reference/ingest-keys.md#restore-ingest-key) 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](https://sparklogs.com/docs/api/reference/registration-tokens.md#create-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](https://sparklogs.com/docs/api/reference/registration-tokens.md#revoke-registration-token). To find its id, list the organization's registration tokens with `status=active` and match the label.
4. [Read the new token](https://sparklogs.com/docs/api/reference/registration-tokens.md#read-registration-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](https://sparklogs.com/docs/api/reference/registration-tokens.md#list-registration-tokens)

Scope: any of `fleet:deploy`, `fleet:write`

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

```bash
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)

```json
{
  "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](https://sparklogs.com/docs/api/reference/registration-tokens.md#create-registration-token)

Scope: any of `fleet:deploy`, `fleet:write`

```bash
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)

Headers: `Cache-Control: no-store`

```json
{
  "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](https://sparklogs.com/docs/api/reference/registration-tokens.md#revoke-registration-token)

Scope: any of `fleet:deploy`, `fleet:write`

```bash
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)

```json
{
  "message": "registration token revoked"
}
```

**`GET /workspaces/{workspace_id}/registration-tokens/{id}`** [Read a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#read-registration-token)

Scope: any of `fleet:deploy`, `fleet:write`

```bash
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)

```json
{
  "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_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.

---

Source: <https://sparklogs.com/docs/api/use-cases/rotate-credentials>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
