Skip to main content

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 tokenWith the scope
Deployment Manager at the client's organizationfleet:deploy

Steps​

1. Find the ingest address​

GET/credential
Read credential metadata

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

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/credential" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "credential": {    "kind": "workspace_key",    "credential_id": "4b1d0000-0000-4000-8000-000000000803",    "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",    "region_id": "us-central",    "scope_restriction": "listed",    "scopes": [      "workspace:read",      "fleet:deploy"    ],    "expires_at": "2027-11-10T09:00:00Z"  },  "message": "credential retrieved"}
GET/regions
List regions
Request
curl -X GET \  "https://engine.sparklogs.app/app-api/regions" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "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

Scope: any of fleet:deployfleet:write

Request
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
Cache-Control: no-store
{  "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 by name and read its secret:

GET/workspaces/{workspace_id}/ingest-keys/{id}/secret
Read an ingest key's secret

Scope: any of fleet:deployfleet:write

Request
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
Cache-Control: no-store
{  "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 has the settings for syslog, OpenTelemetry, HTTPS and common forwarders.

4. Confirm data is arriving​

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

Scope: workspace:read

Filter by organization_id.

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys?organization_id=0a9e0000-0000-4000-8000-000000000105" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "as_of": "2026-11-10T15:05:00Z",  "ingest_keys": [    {      "id": "a9e70000-0000-4000-8000-000000000204",      "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",      "name": "Harbor Dental servers",      "description": null,      "organization_id": "0a9e0000-0000-4000-8000-000000000105",      "path": [        "0a9e0000-0000-4000-8000-000000000100",        "0a9e0000-0000-4000-8000-000000000105",        "a9e70000-0000-4000-8000-000000000204"      ],      "data_status": "online",      "last_data_at": "2026-11-10T14:00:00Z",      "created_at": "2026-11-05T08:00:00Z",      "updated_at": "2026-11-10T14:00:00Z",      "deleted_at": null,      "organization_deleted_at": null    }  ],  "message": "ingest keys retrieved",  "next_cursor": null}

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​

StepResponseCause and fix
2403 with cause token_scopeThe token lacks fleet:deploy.
2403 APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATIONThe token's role does not allow creating keys at that organization, or the id is wrong.
2400 naming organization_idThe 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.