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
- curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/credential" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/credential" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/credential" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "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"}/regions - curl
- PowerShell
- Python
curl -X GET \ "https://engine.sparklogs.app/app-api/regions" \ -H "Authorization: Bearer $SPARKLOGS_TOKEN"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/regions" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/regions" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "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
- curl
- PowerShell
- Python
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" }'$body = @{ name = "Harbor Dental servers" organization_id = "0a9e0000-0000-4000-8000-000000000105"}Invoke-RestMethod -Method Post ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" } ` -ContentType "application/json; charset=utf-8" ` -Body ($body | ConvertTo-Json -Depth 10)import os import requests response = requests.post( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, json={ "name": "Harbor Dental servers", "organization_id": "0a9e0000-0000-4000-8000-000000000105", },)response.raise_for_status(){ "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:
/workspaces/{workspace_id}/ingest-keys/{id}/secret Scope: any of fleet:deployfleet:write
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204/secret" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys/a9e70000-0000-4000-8000-000000000204/secret" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"},)response.raise_for_status(){ "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
/workspaces/{workspace_id}/ingest-keys Scope: workspace:read
Filter by organization_id.
- curl
- PowerShell
- Python
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"Invoke-RestMethod -Method Get ` -Uri "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys?organization_id=0a9e0000-0000-4000-8000-000000000105" ` -Headers @{ Authorization = "Bearer $env:SPARKLOGS_TOKEN" }import os import requests response = requests.get( "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/ingest-keys" , headers={"Authorization": f"Bearer {os.environ['SPARKLOGS_TOKEN']}"}, params={ "organization_id": "0a9e0000-0000-4000-8000-000000000105", },)response.raise_for_status(){ "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.