# Add a Log Source for a Client

Devices that cannot run the agent, such as a firewall or a NAS, send their logs with an ingest key.
This example shows how to create the key in the client's organization and confirm that data is arriving.

## What the token needs

| Give a workspace token | With the scope |
| - | - |
| **Deployment Manager** at the client's organization | `fleet:deploy` |

## Steps

### 1. Find the ingest address

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

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

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

Response (200)

```json
{
  "credential": {
    "kind": "workspace_key",
    "credential_id": "4b1d0000-0000-4000-8000-000000000803",
    "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
    "region_id": "us-central",
    "scope_restriction": "listed",
    "scopes": [
      "workspace:read",
      "fleet:deploy"
    ],
    "expires_at": "2027-11-10T09:00:00Z"
  },
  "message": "credential retrieved"
}
```

**`GET /regions`** [List regions](https://sparklogs.com/docs/api/reference/regions.md#list-regions)

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

Response (200)

```json
{
  "message": "regions retrieved",
  "regions": [
    {
      "id": "us-central",
      "name": "United States",
      "sort_order": 1,
      "ingest_uri": "https://ingest-usc1.engine.sparklogs.app",
      "query_uri": "https://query-usc1.engine.sparklogs.app"
    }
  ]
}
```

The credential response gives the workspace's `region_id`.
In the list of regions, the entry with that id has `ingest_uri`, the address senders use.

### 2. Create the ingest key

**`POST /workspaces/{workspace_id}/ingest-keys`** [Create an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#create-ingest-key)

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

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys" \
  -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"
}
```

Send `organization_id` (the client) and a `name` that identifies the device or service that will use the key.
The response carries the key's secret in `key`.

If the response is lost, do not create another.
Find the key in the [list of ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md#list-ingest-keys) by `name` and read its secret:

**`GET /workspaces/{workspace_id}/ingest-keys/{id}/secret`** [Read an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#reveal-ingest-key)

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

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

### 3. Configure the sender

Give the device the address from step 1 and the key from step 2.
[Ingest data](https://sparklogs.com/docs/ingest.md) has the settings for syslog, OpenTelemetry, HTTPS and common forwarders.

### 4. Confirm data is arriving

**`GET /workspaces/{workspace_id}/ingest-keys`** [List ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md#list-ingest-keys)

Scope: `workspace:read`

Filter by `organization_id`.

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys?organization_id=0a9e0000-0000-4000-8000-000000000105" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "as_of": "2026-11-10T15:05:00Z",
  "ingest_keys": [
    {
      "id": "a9e70000-0000-4000-8000-000000000204",
      "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
      "name": "Harbor Dental servers",
      "description": null,
      "organization_id": "0a9e0000-0000-4000-8000-000000000105",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "0a9e0000-0000-4000-8000-000000000105",
        "a9e70000-0000-4000-8000-000000000204"
      ],
      "data_status": "online",
      "last_data_at": "2026-11-10T14:00:00Z",
      "created_at": "2026-11-05T08:00:00Z",
      "updated_at": "2026-11-10T14:00:00Z",
      "deleted_at": null,
      "organization_deleted_at": null
    }
  ],
  "message": "ingest keys retrieved",
  "next_cursor": null
}
```

`data_status` reads `online` when data arrived with the key in the last three hours, and `last_data_at` shows when data last arrived.
`last_data_at` is updated at most once every five minutes, so it can be behind.

## If a step fails

| Step | Response | Cause and fix |
| - | - | - |
| 2 | 403 with `cause` `token_scope` | The token lacks `fleet:deploy`. |
| 2 | 403 `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` | The token's role does not allow creating keys at that organization, or the id is wrong. |
| 2 | 400 naming `organization_id` | The organization is deleted. |

## Idempotency (safety of repeated API calls)

Creating a key makes a new key every time.
List the client's ingest keys and match your `name` before creating one.

---

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