# Registration tokens

A registration token lets agent installers register new agents into an organization; create, read, reveal, change, revoke, delete and restore them.

Belongs to: [Organizations](https://sparklogs.com/docs/api/reference/organizations.md)

Contains: [Agents](https://sparklogs.com/docs/api/reference/agents.md)

Ids: uuid.

- `GET /workspaces/{workspace_id}/registration-tokens` [List registration tokens](#list-registration-tokens)
- `GET /workspaces/{workspace_id}/registration-tokens/{id}` [Read a registration token](#read-registration-token)
- `POST /workspaces/{workspace_id}/registration-tokens` [Create a registration token](#create-registration-token)
- `PATCH /workspaces/{workspace_id}/registration-tokens/{id}` [Update a registration token](#update-registration-token)
- `DELETE /workspaces/{workspace_id}/registration-tokens/{id}` [Delete a registration token](#delete-registration-token)
- `POST /workspaces/{workspace_id}/registration-tokens/{id}/restore` [Restore a deleted registration token](#restore-registration-token)
- `GET /workspaces/{workspace_id}/registration-tokens/{id}/secret` [Read a registration token's secret](#reveal-registration-token)
- `POST /workspaces/{workspace_id}/registration-tokens/{id}/revoke` [Revoke a registration token](#revoke-registration-token)

## RegistrationToken object

A registration token is a secret agent installers present to register new agents into an organization or one below it.

- `id` (uuid): The token's id.
- `organization_id` (uuid): The organization agents installed with the token register into, or into an organization below it.
- `path` (array of uuid): The organization ids from the top-level organization down to the token's own, then the token's id.
- `label` (string or null): The token's name; null when it has none.
- `status` (one of the values below): Whether agents can register with the token, worked out on a list at the page's `as_of`, the same instant for every page of one walk, and on a read of one token when the response is written: revoked once revoked, else expired once `expires_at` has passed, else active. Whether it is deleted is `deleted_at`. Passing `expires_at` does not change `updated_at`.
  - `active`: Agents can register with it.
  - `revoked`: It was revoked.
  - `expired`: Its `expires_at` has passed.
- `created_by_user_id` (string or null): The member who created the token. Null when you are not shown that member, when the member has left, or when a workspace token created it.
- `expires_at` (date-time or null): When the token stops working; null when it does not expire.
- `revoked_at` (date-time or null): When the token was revoked; null while it is not.
- `revocation_reason` (string or null): Why the token was revoked, as the person revoking it wrote.
- `use_count` (integer): How many times agents registered with the token.
- `last_used_at` (date-time or null): When an agent last registered with the token; null until one does.
- `created_at` (date-time): When the token was created.
- `updated_at` (date-time): When the token's record last changed. Every registration with it changes it.
- `deleted_at` (date-time or null): When the token was deleted; null while it is not.

## List registration tokens

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/registration-tokens`

Preview

Returns the registration tokens you can see, a page at a time, in `id` order, or least recently changed first with `updated_since`, never with their secrets. Seeing a token takes `organization.read` and `registration_token.read` at its organization. Filter by organization, with or without the organizations below it, by `status` and by `label`; filters combine, a row passing every one given. `status` is worked out at the walk's `as_of`, the same instant for every page, and a token passing its `expires_at` does not change its `updated_at`, so a sync from `updated_since` misses it: find expired tokens on a full walk. `deleted=include` or `deleted=only` returns deleted tokens, and tokens of deleted organizations, too.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `fleet:deploy`, `fleet:write`
- Privilege: `registration_token.read`

Needs `registration_token.read`. `registration_token.read` applies at each organization a grant covers and every organization below it. A caller who reaches no organization gets an empty list.

### Behavior

- Retry: Safe to send again
- Paging: Cursor, with sync · 1000 a page by default, up to 5000

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.

### Query parameters

- `organization_id` (uuid): Only tokens of this organization.
- `subtree` (boolean): `true` adds the tokens of every organization below `organization_id`. `true` and `false` are the only values it takes.
  Default: `false`
- `id` (array of string): Only the tokens with these ids. A comma-separated list of at most 100 ids matches any of them.
- `status` (array of one of the values below): Only tokens whose `status` is one of these. A comma-separated list matches any of its values. Worked out at the walk's `as_of`, so a row can start or stop matching without changing: use it on a full walk, never with `updated_since`.
  - `active`: Agents can register with it.
  - `revoked`: It was revoked.
  - `expired`: Its `expires_at` has passed.
- `label` (string): Only tokens of this label: the way to find a token created by a call whose answer was lost. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.
- `deleted` (one of the values below): Which tokens to list, by whether they or their organization are deleted.
  Default: `exclude`
  - `exclude`: Tokens that are not deleted, in an organization that is not deleted. The default.
  - `include`: Every token, deleted ones and those of deleted organizations included.
  - `only`: Tokens that are deleted or whose organization is.
- `updated_since` (date-time): Only tokens changed at or after this time (RFC 3339). Pass the watermark of your last complete sync.
- `limit` (integer): How many tokens a page holds: 1 to 5000, 1000 by default.
  Default: `1000` · 1 to 5000
- `cursor` (string): The `next_cursor` of the previous page, with the same filters.
- `fields` (array of string): Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: `id`, `organization_id`, `path`, `label`, `status`, `created_by_user_id`, `expires_at`, `revoked_at`, `revocation_reason`, `use_count`, `last_used_at`, `created_at`, `updated_at`, `deleted_at`

### Response (200)

- `registration_tokens` (array of RegistrationToken, required): The registration tokens on this page.
- `next_cursor` (string or null, required): Null on the last page. Otherwise pass it as `cursor` for the next page.
- `watermark` (date-time, required): Pass it as `updated_since` on your next sync.
- `as_of` (date-time, required): The instant this walk's values worked out from the clock, and its filters on them, are worked out at: fixed on the first page and the same on every page after it.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, one given twice, or `fields` naming a field it does not have. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `organization_id` is not a UUID, `subtree` is neither `true` nor `false` or comes without it, `deleted` is not a value it takes, or `limit` is out of range, `cursor` cannot be read or was sent with other filters, or `updated_since` is not a valid time. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `organization.read` and `registration_token.read`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [Read a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#read-registration-token)
- [Create a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#create-registration-token)
- [Update a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#update-registration-token)
- [Delete a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#delete-registration-token)
- [Restore a deleted registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#restore-registration-token)
- [Read a registration token's secret](https://sparklogs.com/docs/api/reference/registration-tokens.md#reveal-registration-token)
- [Revoke a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#revoke-registration-token)

### Example

List the active registration tokens

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens?status=active" \
  -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
    },
    {
      "id": "7e0c0000-0000-4000-8000-000000000303",
      "organization_id": "0a9e0000-0000-4000-8000-000000000100",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "7e0c0000-0000-4000-8000-000000000303"
      ],
      "label": "Northwind clients agents",
      "status": "active",
      "created_by_user_id": "AlexRiveraExampleUserId00001",
      "expires_at": null,
      "revoked_at": null,
      "revocation_reason": null,
      "use_count": 1,
      "last_used_at": "2026-11-04T09:00:00Z",
      "created_at": "2026-11-01T10:00:00Z",
      "updated_at": "2026-11-04T09:00:00Z",
      "deleted_at": null
    }
  ],
  "watermark": "2026-11-10T09:00:00Z"
}
```

## Read a registration token

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/registration-tokens/{id}`

Preview

Returns one registration token you can see, deleted or not, without its secret. One you cannot see returns 404, as one that does not exist does.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `fleet:deploy`, `fleet:write`
- Privilege: `registration_token.read`

Needs `registration_token.read`. `registration_token.read` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Safe to send again

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The registration token's id.

### Query parameters

- `fields` (array of string): Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: `id`, `organization_id`, `path`, `label`, `status`, `created_by_user_id`, `expires_at`, `revoked_at`, `revocation_reason`, `use_count`, `last_used_at`, `created_at`, `updated_at`, `deleted_at`

### Response (200)

- `registration_token` (RegistrationToken, required): The registration token.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, one given twice, or `fields` naming a field it does not have. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `organization.read` and `registration_token.read`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | No such registration token, or one you cannot see. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List registration tokens](https://sparklogs.com/docs/api/reference/registration-tokens.md#list-registration-tokens)
- [Create a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#create-registration-token)
- [Update a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#update-registration-token)
- [Delete a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#delete-registration-token)
- [Restore a deleted registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#restore-registration-token)
- [Read a registration token's secret](https://sparklogs.com/docs/api/reference/registration-tokens.md#reveal-registration-token)
- [Revoke a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#revoke-registration-token)

### Example

Read a registration token

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "registration token retrieved",
  "registration_token": {
    "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
  }
}
```

## Create a registration token

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/registration-tokens`

Preview · Returns a secret

Creates a token that agent installers present to register into `organization_id` or an organization below it, and returns it. Needs `registration_token.create` at that organization. An install that passes an RMM or PSA client id lands in the organization at or below `organization_id` that records that id, ignoring case, a live one before a deleted one, and fails when the best match is deleted. With no match it creates a new organization directly under `organization_id`, named from the install's client name, so record the id your RMM passes on the client's organization before deploying.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `fleet:deploy`, `fleet:write`
- Privilege: `registration_token.create`

Needs `registration_token.create`. `registration_token.create` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Read before sending again
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.

### Request body

- `organization_id` (uuid, required): The organization whose subtree agents installed with the token register into: this organization or one below it. Installs with a client id that matches no organization below it create one directly under it. Required.
- `label` (string or null): A name for the token. Cleaned, as every name is.
  at most 256 characters
- `expires_at` (date-time or null): When the token stops working; leave it out for a token that does not expire. RFC 3339, an offset and fractions of a second allowed; a past time creates an expired token.

### Response (200)

- `id` (uuid, required): The new registration token's id.
- `token` (string, required): The token an agent installer presents to register. Keep it secret; it can be read again later by anyone holding `registration_token.reveal`.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`. | No |
| 400 | `APP_API_ERR_MISSING_PARAMETER` | `organization_id` is left out. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `organization_id` is not a UUID or names a deleted organization, or `expires_at` is not a valid time. | No |
| 400 | `APP_API_ERR_PARAMETER_TOO_LONG` | `label` is longer than 256 characters. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | You do not hold `registration_token.create` at `organization_id`, or it names no organization you can see. The same refusal comes when the path names a workspace other than the token's own. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List registration tokens](https://sparklogs.com/docs/api/reference/registration-tokens.md#list-registration-tokens)
- [Read a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#read-registration-token)
- [Update a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#update-registration-token)
- [Delete a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#delete-registration-token)
- [Restore a deleted registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#restore-registration-token)
- [Read a registration token's secret](https://sparklogs.com/docs/api/reference/registration-tokens.md#reveal-registration-token)
- [Revoke a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#revoke-registration-token)

### Example

Create a registration token for Lakeside Clinic

```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-11-30T00:00:00Z",
    "label": "Lakeside Clinic rollout",
    "organization_id": "0a9e0000-0000-4000-8000-000000000101"
  }'
```

Response (200)

Headers: `Cache-Control: no-store`

```json
{
  "message": "registration token created",
  "id": "7e0c0000-0000-4000-8000-000000000301",
  "token": "EXAMPLE-REGISTRATION-TOKEN-NOT-REAL"
}
```

## Update a registration token

`PATCH https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/registration-tokens/{id}`

Preview

Changes a registration token's label or expiry; a field left out keeps its value, and an `expires_at` of null removes the expiry. Moving `expires_at` later, or to null, makes an expired token active again with the same secret; a revoked token stays revoked. Needs `registration_token.revoke` at the token's organization.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `fleet:deploy`, `fleet:write`
- Privilege: `registration_token.revoke`

Needs `registration_token.revoke`. `registration_token.revoke` applies at each organization a grant covers and every organization below it. `registration_token.revoke` also admits updating, deleting and restoring a registration token, not only revoking it.

### Behavior

- Retry: Safe to repeat: ends in the same state
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The registration token's id.

### Request body

No field is required. Send no body to accept the defaults.

- `label` (string or null): The new label. Cleaned, as every name is. `null` or an empty string clears it.
  left out keeps · `null` clears · empty string clears
  at most 256 characters
- `expires_at` (date-time or null): The new expiry. Cleared, the token does not expire. `null` or an empty string clears it.
  left out keeps · `null` clears · empty string clears

### Response (200)

- `id` (uuid, required): The id of the row the call created or changed.
- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `expires_at` is not a valid time. | No |
| 400 | `APP_API_ERR_PARAMETER_TOO_LONG` | `label` is longer than 256 characters. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own. | No |
| 409 | `APP_API_ERR_CONFLICT` | The token is deleted: restore it first. | Read first |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List registration tokens](https://sparklogs.com/docs/api/reference/registration-tokens.md#list-registration-tokens)
- [Read a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#read-registration-token)
- [Create a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#create-registration-token)
- [Delete a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#delete-registration-token)
- [Restore a deleted registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#restore-registration-token)
- [Read a registration token's secret](https://sparklogs.com/docs/api/reference/registration-tokens.md#reveal-registration-token)
- [Revoke a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#revoke-registration-token)

### Example

Rename a registration token

```bash
curl -X PATCH \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Lakeside Clinic, all sites"
  }'
```

Response (200)

```json
{
  "message": "registration token updated",
  "id": "7e0c0000-0000-4000-8000-000000000301"
}
```

## Delete a registration token

`DELETE https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/registration-tokens/{id}`

Preview · Destructive

Marks a registration token deleted. Needs `registration_token.revoke` at the token's organization. Deleting a deleted token changes nothing.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `fleet:deploy`, `fleet:write`
- Privilege: `registration_token.revoke`

Needs `registration_token.revoke`. `registration_token.revoke` applies at each organization a grant covers and every organization below it. `registration_token.revoke` also admits updating, deleting and restoring a registration token, not only revoking it.

### Behavior

- Retry: Safe to repeat: ends in the same state
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The registration token's id.

### Response (200)

- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, or one given twice. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The request carries a body other than nothing, `null` or `{}`: a delete takes none, and its options are query parameters; `parameter` names the body's first field, or `body`. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List registration tokens](https://sparklogs.com/docs/api/reference/registration-tokens.md#list-registration-tokens)
- [Read a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#read-registration-token)
- [Create a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#create-registration-token)
- [Update a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#update-registration-token)
- [Restore a deleted registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#restore-registration-token)
- [Read a registration token's secret](https://sparklogs.com/docs/api/reference/registration-tokens.md#reveal-registration-token)
- [Revoke a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#revoke-registration-token)

### Example

Delete a registration token

```bash
curl -X DELETE \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

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

## Restore a deleted registration token

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/registration-tokens/{id}/restore`

Preview

Restores a deleted registration token; a revoked or expired token stays so. Needs `registration_token.revoke` at the token's organization. Restoring a live one changes nothing.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `fleet:deploy`, `fleet:write`
- Privilege: `registration_token.revoke`

Needs `registration_token.revoke`. `registration_token.revoke` applies at each organization a grant covers and every organization below it. `registration_token.revoke` also admits updating, deleting and restoring a registration token, not only revoking it.

### Behavior

- Retry: Safe to repeat: ends in the same state
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The registration token's id.

### Response (200)

- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The body is not a JSON object, is not sent as `application/json`, or names a field: the call takes none. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List registration tokens](https://sparklogs.com/docs/api/reference/registration-tokens.md#list-registration-tokens)
- [Read a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#read-registration-token)
- [Create a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#create-registration-token)
- [Update a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#update-registration-token)
- [Delete a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#delete-registration-token)
- [Read a registration token's secret](https://sparklogs.com/docs/api/reference/registration-tokens.md#reveal-registration-token)
- [Revoke a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#revoke-registration-token)

### Example

Restore a deleted registration token

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/restore" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

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

## Read a registration token's secret

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/registration-tokens/{id}/secret`

Preview · Returns a secret

Returns the token agent installers present. Needs `registration_token.reveal` at the token's organization. Every call is recorded in the audit log. A deleted token returns 404.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `fleet:deploy`, `fleet:write`
- Privilege: `registration_token.reveal`

Needs `registration_token.reveal`. `registration_token.reveal` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Safe to send again
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The registration token's id.

### Response (200)

- `token` (string, required): The token an agent installer presents to register.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, or one given twice. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own. | No |
| 409 | `APP_API_ERR_CONFLICT` | The token is deleted: restore it first. | Read first |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List registration tokens](https://sparklogs.com/docs/api/reference/registration-tokens.md#list-registration-tokens)
- [Read a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#read-registration-token)
- [Create a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#create-registration-token)
- [Update a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#update-registration-token)
- [Delete a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#delete-registration-token)
- [Restore a deleted registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#restore-registration-token)
- [Revoke a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#revoke-registration-token)

### Example

Read a registration token's secret

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/registration-tokens/7e0c0000-0000-4000-8000-000000000301/secret" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

Headers: `Cache-Control: no-store`

```json
{
  "message": "registration token retrieved",
  "token": "EXAMPLE-REGISTRATION-TOKEN-NOT-REAL"
}
```

## Revoke a registration token

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/registration-tokens/{id}/revoke`

Preview · Destructive

Revokes a registration token: agents can no longer register with it, and agents already registered keep working. Revoking cannot be undone. Needs `registration_token.revoke` at the token's organization. Revoking a revoked token changes nothing.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `fleet:deploy`, `fleet:write`
- Privilege: `registration_token.revoke`

Needs `registration_token.revoke`. `registration_token.revoke` applies at each organization a grant covers and every organization below it. `registration_token.revoke` also admits updating, deleting and restoring a registration token, not only revoking it.

### Behavior

- Retry: Safe to repeat: ends in the same state
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The registration token's id.

### Request body

No field is required. Send no body to accept the defaults.

- `reason` (string or null): Why the token is revoked, for whoever reads it later.
  at most 1024 characters

### Response (200)

- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`. | No |
| 400 | `APP_API_ERR_PARAMETER_TOO_LONG` | `reason` is longer than 1024 characters. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The object does not exist, is in another workspace or is outside your reach, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own. | No |
| 409 | `APP_API_ERR_CONFLICT` | The token is deleted: restore it first. | Read first |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List registration tokens](https://sparklogs.com/docs/api/reference/registration-tokens.md#list-registration-tokens)
- [Read a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#read-registration-token)
- [Create a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#create-registration-token)
- [Update a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#update-registration-token)
- [Delete a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#delete-registration-token)
- [Restore a deleted registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#restore-registration-token)
- [Read a registration token's secret](https://sparklogs.com/docs/api/reference/registration-tokens.md#reveal-registration-token)

### Example

Revoke a registration token once the rollout is done

```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": "Rollout finished"
  }'
```

Response (200)

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

---

Source: <https://sparklogs.com/docs/api/reference/registration-tokens>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
