Managing API Keys

Overview

API keys authenticate machine-to-machine traffic — the Edge Agent pushing readings, or a script sending data straight to the ingestion endpoint. Unlike a user login, an API key is a long-lived credential meant for non-interactive systems.

Interactive access — reading and managing data through the API — uses a short-lived Bearer JWT instead. See Authentication.

Use case	Credential
Edge Agent pushing sensor data	API key
Direct ingestion from a script or job	API key
Interactive user session in a browser or app	Bearer JWT

An API key is scoped to sending machine data. It cannot manage users, billing, alert rules, notification channels, integrations, or any other account setting — those actions always require a signed-in user (JWT). This keeps a leaked ingestion key from becoming an account takeover.

Creating a key

Create keys from the Client Portal (Settings → API Keys) or from the API. In both cases, only an account administrator can create a key.

POST /api/v1/api-keys takes a single field — a descriptive name:

curl -X POST "https://api.haltless.io/api/v1/api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "edge-agent-plant-1" }'

Response (201 Created):

{
  "id": "b1e7c0a2-3d4e-4f5a-9b6c-7d8e9f0a1b2c",
  "name": "edge-agent-plant-1",
  "key": "hlts_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "created_at": "2026-08-05T10:00:00Z"
}

warning

The key value is returned only once, at creation. Store it in a secrets manager immediately. If you lose it, revoke the key and create a new one — there is no way to retrieve it later.

Using a key

Send the key in the X-API-Key header on every request:

curl -X POST "https://api.haltless.io/api/v1/ingest" \
  -H "X-API-Key: hlts_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Content-Type: application/json" \
  -d '{ "readings": [] }'

An invalid or revoked key returns 401 Unauthorized.

To push readings with a key, see Direct Ingestion. To configure the Edge Agent with a key, see the Edge Agent configuration guide.

Listing keys

List the keys on your account. The secret is never returned — only a short, non-sensitive prefix so you can tell keys apart:

curl "https://api.haltless.io/api/v1/api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

[
  {
    "id": "b1e7c0a2-3d4e-4f5a-9b6c-7d8e9f0a1b2c",
    "name": "edge-agent-plant-1",
    "key_prefix": "hlts_a1b2c3...",
    "is_active": true,
    "created_at": "2026-08-05T10:00:00Z"
  }
]

Revoking a key

Revoke a key the moment it is compromised, retired, or replaced:

curl -X DELETE "https://api.haltless.io/api/v1/settings/api-keys/KEY_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Revocation takes effect immediately. Any request using the revoked key receives 401 Unauthorized.

Rotating keys with zero downtime

Because more than one key can be active at once, rotation needs no downtime:

1. Create a new key with a fresh name (for example, edge-agent-plant-1-2026-q3).
2. Deploy the new key to the agent or system that uses it.
3. Confirm data is still flowing on the new key.
4. Revoke the old key once you have confirmed the new one is in use.

Security best practices

1. Treat keys as secrets. Never commit them to version control or paste them into tickets. Use environment variables or a secrets manager.
2. One key per system. Don't share a single key across multiple agents; per-system keys make rotation and revocation surgical.
3. Use descriptive names. Encode the system and environment in the name so you can identify a key at a glance.
4. Rotate periodically. Quarterly rotation is a sensible default.
5. Revoke on exposure. If a key ever appears in a log, error message, or repository, revoke it immediately and issue a new one.

Rate limits

Requests authenticated with an API key count toward your account's rate limits, the same as any other request. The ingestion endpoint accepts up to 240 requests per minute; because each request can carry a large batch of readings, this supports high sustained throughput. See Rate Limiting.