# Ingest keys

An ingest key lets a sender other than a SparkLogs Agent send log data for an organization; list and read them, create one, read or replace its secret, and rename, move, delete or restore one.

A SparkLogs Agent's id names no ingest key here, and returns 404 to a read and 403 to a change, as an id that does not exist does.

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

Ids: uuid.

- `GET /workspaces/{workspace_id}/ingest-keys` [List ingest keys](#list-ingest-keys)
- `GET /workspaces/{workspace_id}/ingest-keys/{id}` [Read an ingest key](#read-ingest-key)
- `POST /workspaces/{workspace_id}/ingest-keys` [Create an ingest key](#create-ingest-key)
- `PATCH /workspaces/{workspace_id}/ingest-keys/{id}` [Update an ingest key](#update-ingest-key)
- `DELETE /workspaces/{workspace_id}/ingest-keys/{id}` [Delete an ingest key](#delete-ingest-key)
- `POST /workspaces/{workspace_id}/ingest-keys/{id}/restore` [Restore a deleted ingest key](#restore-ingest-key)
- `POST /workspaces/{workspace_id}/ingest-keys/{id}/move` [Move an ingest key](#move-ingest-key)
- `GET /workspaces/{workspace_id}/ingest-keys/{id}/secret` [Read an ingest key's secret](#reveal-ingest-key)
- `POST /workspaces/{workspace_id}/ingest-keys/{id}/rotate` [Replace an ingest key's secret](#rotate-ingest-key)

## IngestKey object

An ingest key is a secret a sender other than a SparkLogs Agent presents to send log data for one organization.

- `id` (uuid): The ingest key's id.
- `workspace_id` (uuid): The workspace the ingest key belongs to.
- `name` (string or null): The ingest key's name, a label that changes only when you change it.
- `description` (string or null): The ingest key's description.
- `organization_id` (uuid): The organization the ingest key sends data for.
- `path` (array of uuid or null): The organization ids from the top-level organization down to the key's own, then the key's id.
- `data_status` (one of the values below): Whether data is arriving with the key, worked out from when its data last arrived: on a list at the page's `as_of`, the same instant for every page of one walk, and on a read of one key when the response is written. A key has no heartbeat, so a sender that sends nothing for hours reads offline. The SparkLogs MCP server shows the same value as `agent_status` on an ingest key's row.
  - `online`: Data arrived with the key in the last 3 hours.
  - `offline`: No data has arrived with it for longer than that.
  - `never_seen`: No data has arrived with it yet.
  - `deleted`: The ingest key is deleted.
- `last_data_at` (date-time or null): When log data sent with the key last arrived, recorded at most once every five minutes. Null until data first arrives.
- `created_at` (date-time): When the ingest key was created.
- `updated_at` (date-time): When the ingest key's record last changed. Arriving data changes it, so it says little about when anything else about the key changed.
- `deleted_at` (date-time or null): When the ingest key was deleted; null while it is live.
- `organization_deleted_at` (date-time or null): When the key's organization was deleted; null while the organization is live.
- `custom_fields` (map of any or null): Custom fields recorded on the ingest key, as an object of string, number and boolean values. Not for secrets: anyone who may read the ingest key may read them.

## List ingest keys

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/ingest-keys`

Preview

Returns the ingest keys you can see, a page at a time, in `id` order, never with their secrets. Seeing a key takes `organization.read` and `agent.read` at its organization. Filter by organization, with or without the organizations below it, by `name`, or by inactivity; filters combine, a row passing every one given. A moving `inactive_before` cutoff, such as 14 days before now, and `data_status` are worked out at the walk's `as_of`, the same instant for every page.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `workspace:read`
- Privilege: `agent.read`

Needs `agent.read`. `agent.read` applies at each organization a grant covers and every organization below it. `agent.read` also admits reading ingest keys, but never their secrets. A caller who reaches no organization gets an empty list.

### Behavior

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

### Path parameters

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

### Query parameters

- `organization_id` (uuid): Only ingest keys of this organization.
- `subtree` (boolean): `true` adds the ingest keys of every organization below `organization_id`. `true` and `false` are the only values it takes.
  Default: `false`
- `id` (array of string): Only the ingest keys with these ids. A comma-separated list of at most 100 ids matches any of them.
- `name` (string): Only ingest keys of this name: the way to find a key 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.
- `inactive_before` (date-time): Only ingest keys created, and last sending data, before this time: keys gone quiet, at a cutoff you choose. An RFC 3339 time.
- `deleted` (one of the values below): Which ingest keys to list, by whether they or their organization are deleted.
  Default: `exclude`
  - `exclude`: Ingest keys that are live in a live organization. The default.
  - `include`: Every ingest key, deleted ones and those of deleted organizations included.
  - `only`: Ingest keys that are deleted or whose organization is.
- `limit` (integer): How many ingest keys 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`, `workspace_id`, `name`, `description`, `organization_id`, `path`, `data_status`, `last_data_at`, `created_at`, `updated_at`, `deleted_at`, `organization_deleted_at`

Sent only when named in `fields`: `custom_fields`

### Response (200)

- `ingest_keys` (array of IngestKey, required): The ingest keys on this page.
- `next_cursor` (string or null, required): Null on the last page. Otherwise pass it as `cursor` for the next page.
- `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 `organization_id`, `deleted` is not a value it takes, or `limit` is out of range, or `cursor` cannot be read or was sent with other filters. | 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 `agent.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 an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#read-ingest-key)
- [Create an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#create-ingest-key)
- [Update an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#update-ingest-key)
- [Delete an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#delete-ingest-key)
- [Restore a deleted ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#restore-ingest-key)
- [Move an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#move-ingest-key)
- [Read an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#reveal-ingest-key)
- [Replace an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#rotate-ingest-key)

### Example

List every ingest key

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys" \
  -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
    },
    {
      "id": "a9e70000-0000-4000-8000-000000000205",
      "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
      "name": "Lakeside Clinic firewall",
      "description": "Syslog from the front office firewall",
      "organization_id": "0a9e0000-0000-4000-8000-000000000101",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "0a9e0000-0000-4000-8000-000000000101",
        "a9e70000-0000-4000-8000-000000000205"
      ],
      "data_status": "online",
      "last_data_at": "2026-11-10T15:00:00Z",
      "created_at": "2026-11-03T14:00:00Z",
      "updated_at": "2026-11-10T15:00:00Z",
      "deleted_at": null,
      "organization_deleted_at": null
    }
  ],
  "message": "ingest keys retrieved",
  "next_cursor": null
}
```

## Read an ingest key

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

Preview

Returns one ingest key you can see, deleted or not, without its secret. One you cannot see returns 404, as one that does not exist does, and so does the id of a SparkLogs Agent.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `workspace:read`
- Privilege: `agent.read`

Needs `agent.read`. `agent.read` applies at each organization a grant covers and every organization below it. `agent.read` also admits reading ingest keys, but never their secrets.

### Behavior

- Retry: Safe to send again

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The ingest key'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`, `workspace_id`, `name`, `description`, `organization_id`, `path`, `data_status`, `last_data_at`, `created_at`, `updated_at`, `deleted_at`, `organization_deleted_at`

Sent only when named in `fields`: `custom_fields`

### Response (200)

- `ingest_key` (IngestKey, required): The ingest key.
- `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 `agent.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 ingest key, or one you cannot see; a SparkLogs Agent's id answers this too. | 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 ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md#list-ingest-keys)
- [Create an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#create-ingest-key)
- [Update an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#update-ingest-key)
- [Delete an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#delete-ingest-key)
- [Restore a deleted ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#restore-ingest-key)
- [Move an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#move-ingest-key)
- [Read an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#reveal-ingest-key)
- [Replace an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#rotate-ingest-key)

### Example

Read an ingest key

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "ingest_key": {
    "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 key retrieved"
}
```

## Create an ingest key

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/ingest-keys`

Preview · Returns a secret

Creates an ingest key for `organization_id` and returns the key senders present. Needs `ingest_key.create` at that organization.

### Access

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

Needs `ingest_key.create`. `ingest_key.create` applies at each organization a grant covers and every organization below it. `ingest_key.create` also admits moving a SparkLogs Agent or an ingest key into an organization, with `agent.write` at the one it leaves.

### 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 the ingest key sends data for. Required.
- `name` (string, required): The ingest key's name. Cleaned, as every name is. Required.
  at most 128 characters
- `description` (string or null): The ingest key's description.
  at most 2048 characters

### Response (200)

- `id` (uuid, required): The new ingest key's id.
- `key` (string, required): The key a sender presents to send log data. Keep it secret; it can be read again later by anyone holding `ingest_key.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` or `name` is left out or empty. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `organization_id` is not a UUID or names a deleted organization. | No |
| 400 | `APP_API_ERR_PARAMETER_TOO_LONG` | `name` is longer than 128 characters, or `description` longer than 2048. | 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 `ingest_key.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 ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md#list-ingest-keys)
- [Read an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#read-ingest-key)
- [Update an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#update-ingest-key)
- [Delete an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#delete-ingest-key)
- [Restore a deleted ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#restore-ingest-key)
- [Move an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#move-ingest-key)
- [Read an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#reveal-ingest-key)
- [Replace an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#rotate-ingest-key)

### Example

Create an ingest key for Harbor Dental's servers

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbor Dental servers",
    "organization_id": "0a9e0000-0000-4000-8000-000000000105"
  }'
```

Response (200)

Headers: `Cache-Control: no-store`

```json
{
  "message": "ingest key created",
  "id": "a9e70000-0000-4000-8000-000000000204",
  "key": "EXAMPLE-INGEST-KEY-NOT-A-REAL-SECRET"
}
```

## Update an ingest key

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

Preview

Changes an ingest key's name, description or custom fields; a field left out keeps its value. Needs `agent.write` at its organization.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `fleet:write`
- Privilege: `agent.write`

Needs `agent.write`. `agent.write` applies at each organization a grant covers and every organization below it. `agent.write` also admits changing and moving ingest keys.

### 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 ingest key's id.

### Request body

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

- `name` (string): The new name, a label only. Cleaned, as every name is. `null` or an empty string returns 400.
  left out keeps · `null` is refused · empty string is refused
  at most 128 characters
- `description` (string or null): The new description. `null` or an empty string clears it.
  left out keeps · `null` clears · empty string clears
  at most 2048 characters
- `custom_fields` (map of any or null): Changes to the custom fields, merged into the stored ones: a key left out keeps its value, null removes it, and a string, a boolean, or a number of at most 32 characters in plain decimal digits with no exponent sets it. A number is kept by its value, so 1.50 reads back as 1.5. At most 50 keys, each 1 to 64 letters, digits, `_`, `-` and `.`, and 8 KiB as JSON. Write a time as RFC 3339 in UTC. Not for secrets.

### 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` | `name` is empty. | No |
| 400 | `APP_API_ERR_PARAMETER_TOO_LONG` | `name` is longer than 128 characters, or `description` longer than 2048. | 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 ingest key does not exist, is in another workspace or is outside your reach, `id` names a SparkLogs Agent, 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 ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md#list-ingest-keys)
- [Read an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#read-ingest-key)
- [Create an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#create-ingest-key)
- [Delete an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#delete-ingest-key)
- [Restore a deleted ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#restore-ingest-key)
- [Move an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#move-ingest-key)
- [Read an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#reveal-ingest-key)
- [Replace an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#rotate-ingest-key)

### Example

Rename an ingest key

```bash
curl -X PATCH \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbor Dental server room"
  }'
```

Response (200)

```json
{
  "message": "ingest key updated",
  "id": "a9e70000-0000-4000-8000-000000000204"
}
```

## Delete an ingest key

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

Preview · Destructive

Marks an ingest key deleted; senders using it are refused from then on, and `cache_clear_status` says whether every region refuses it. Needs `agent.delete` at its organization. Deleting a deleted key changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `fleet:write`
- Privilege: `agent.delete`

Needs `agent.delete`. `agent.delete` applies at each organization a grant covers and every organization below it. `agent.delete` also admits deleting and restoring ingest keys.

### 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 ingest key'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 ingest key does not exist, is in another workspace or is outside your reach, `id` names a SparkLogs Agent, 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 ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md#list-ingest-keys)
- [Read an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#read-ingest-key)
- [Create an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#create-ingest-key)
- [Update an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#update-ingest-key)
- [Restore a deleted ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#restore-ingest-key)
- [Move an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#move-ingest-key)
- [Read an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#reveal-ingest-key)
- [Replace an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#rotate-ingest-key)

### Example

Delete a client's ingest key

```bash
curl -X DELETE \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000205" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "ingest key deleted",
  "cache_clear_status": "ok"
}
```

## Restore a deleted ingest key

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

Preview

Restores a deleted ingest key, so senders using it are accepted again. Needs `agent.delete` at its organization. Restoring a live key changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `fleet:write`
- Privilege: `agent.delete`

Needs `agent.delete`. `agent.delete` applies at each organization a grant covers and every organization below it. `agent.delete` also admits deleting and restoring ingest keys.

### 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 ingest key'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 ingest key does not exist, is in another workspace or is outside your reach, `id` names a SparkLogs Agent, 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_CANNOT_RESTORE_PARENT_DELETED` | Its organization is deleted. | 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 ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md#list-ingest-keys)
- [Read an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#read-ingest-key)
- [Create an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#create-ingest-key)
- [Update an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#update-ingest-key)
- [Delete an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#delete-ingest-key)
- [Move an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#move-ingest-key)
- [Read an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#reveal-ingest-key)
- [Replace an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#rotate-ingest-key)

### Example

Restore a deleted ingest key

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000205/restore" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "ingest key restored",
  "cache_clear_status": "ok"
}
```

## Move an ingest key

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/ingest-keys/{id}/move`

Preview

Moves an ingest key to another organization; data sent with it from then on belongs to the new one. Needs `agent.write` at its organization and `ingest_key.create` at the new one. Moving it where it already is changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `fleet:write`
- Privilege: `agent.write`, `ingest_key.create`

Needs `agent.write` at the organization it is in now and `ingest_key.create` at the organization it moves to. `agent.write` applies at each organization a grant covers and every organization below it. `agent.write` also admits changing and moving ingest keys. `ingest_key.create` applies at each organization a grant covers and every organization below it. `ingest_key.create` also admits moving a SparkLogs Agent or an ingest key into an organization, with `agent.write` at the one it leaves.

### 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 ingest key's id.

### Request body

- `organization_id` (uuid, required): The organization to move it to. Moving needs `agent.write` at the key's organization and `ingest_key.create` at this one. Required.

### 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_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 for a live key. | 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 ingest key or the new organization does not exist or is outside your reach, `id` names a SparkLogs Agent, or you do not hold `agent.write` at the key's organization and `ingest_key.create` at the new one. 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 ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md#list-ingest-keys)
- [Read an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#read-ingest-key)
- [Create an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#create-ingest-key)
- [Update an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#update-ingest-key)
- [Delete an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#delete-ingest-key)
- [Restore a deleted ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#restore-ingest-key)
- [Read an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#reveal-ingest-key)
- [Replace an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#rotate-ingest-key)

### Example

Move an ingest key to Lakeside Clinic

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204/move" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "0a9e0000-0000-4000-8000-000000000101"
  }'
```

Response (200)

```json
{
  "message": "ingest key moved",
  "cache_clear_status": "ok"
}
```

## Read an ingest key's secret

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

Preview · Returns a secret

Returns the key senders present. It changes nothing. Needs `ingest_key.reveal` at the ingest key's organization. Every call is recorded in the audit log.

### Access

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

Needs `ingest_key.reveal`. `ingest_key.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 ingest key's id.

### Response (200)

- `key` (string, required): The key a sender presents to send log data.
- `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`) | You do not hold `ingest_key.reveal` at its organization, or it is missing, outside your reach or a SparkLogs Agent. The same refusal comes when the path names a workspace other than the token's own. | No |
| 409 | `APP_API_ERR_CONFLICT` | The ingest key 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 ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md#list-ingest-keys)
- [Read an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#read-ingest-key)
- [Create an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#create-ingest-key)
- [Update an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#update-ingest-key)
- [Delete an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#delete-ingest-key)
- [Restore a deleted ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#restore-ingest-key)
- [Move an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#move-ingest-key)
- [Replace an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#rotate-ingest-key)

### Example

Read an ingest key's secret

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204/secret" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

Headers: `Cache-Control: no-store`

```json
{
  "message": "key retrieved",
  "key": "EXAMPLE-INGEST-KEY-NOT-A-REAL-SECRET"
}
```

## Replace an ingest key's secret

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/ingest-keys/{id}/rotate`

Preview · Returns a secret · Destructive

Replaces the key senders present with a new one and returns it; senders still using the old key are refused from then on, and `cache_clear_status` says whether every region refuses it. Needs `ingest_key.rotate` at the ingest key's organization. Every call is recorded in the audit log. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.

### Access

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

Needs `ingest_key.rotate`. `ingest_key.rotate` 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.
- `id` (uuid, required): The ingest key's id.

### Response (200)

- `key` (string, required): The new key a sender presents to send log data.
- `cache_clear_status` (one of the values below, required): Whether every region refuses the old key.
  - `ok`: Every region refuses the old key.
  - `failed`: A region could not be reached. The old key can keep working there until its cache expires.
  - `disabled`: This environment does not clear regional caches. The old key can keep working until each region's 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`) | You do not hold `ingest_key.rotate` at its organization, or it is missing, outside your reach or a SparkLogs Agent. The same refusal comes when the path names a workspace other than the token's own. | No |
| 409 | `APP_API_ERR_CONFLICT` | The ingest key 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 ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md#list-ingest-keys)
- [Read an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#read-ingest-key)
- [Create an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#create-ingest-key)
- [Update an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#update-ingest-key)
- [Delete an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#delete-ingest-key)
- [Restore a deleted ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#restore-ingest-key)
- [Move an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#move-ingest-key)
- [Read an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#reveal-ingest-key)

### Example

Replace an ingest key's secret

```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"
}
```

---

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