Managing API Keys

API keys provide machine-to-machine authentication for edge agents, scripts, and third-party integrations. This guide covers creating, rotating, and revoking keys securely.

When to use API keys vs JWT tokens

Use case	Auth method
Edge agent pushing sensor data	API key
Automated scripts / cron jobs	API key
CI/CD pipeline integration	API key
Interactive user sessions (dashboard)	JWT token
Mobile / PWA apps	JWT token

API keys are long-lived credentials designed for non-interactive contexts. They are scoped to a tenant and carry the permissions of the user who created them.

Scopes

Every API key has a set of scopes that control exactly which endpoints it can access. This follows the principle of least privilege , an edge agent key should never be able to delete machines or manage billing.

Available scopes

Scope	Grants access to	Typical use
ingest	POST /ingest	Push sensor data batches
agent	GET /agent/heartbeat	Edge agent health check
read:machines	GET /machines, GET /machines/{id}	BI dashboards, monitoring tools
read:sensors	GET /sensor-data/*	Analytics, reporting tools

Presets

Instead of listing individual scopes, you can pass a preset name:

Preset	Expands to	Best for
edge_agent	["ingest", "agent"]	Edge agents (default)
read_only	["read:machines", "read:sensors"]	Dashboards, BI tools

What API keys cannot do

API keys are restricted to the scopes listed above. They cannot access any administrative, user management, billing, or configuration endpoints , regardless of scopes. These actions require a JWT token from an interactive user session:

• User management (create, delete, role changes)
• Billing and subscription management
• Password and MFA changes
• Alert rule and notification channel management
• ERP connection management
• AI settings, role permissions, dashboard presets
• Data retention cleanup

If an API key is used on an endpoint outside its scopes, the server returns 403 Forbidden.

Creating an API key

Only admin users can create API keys.

curl -X POST "https://api.haltless.io/api/v1/settings/api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "edge-agent-prod",
    "scopes": ["ingest", "agent"],
    "expires_at": "2027-04-04T00:00:00Z"
  }'

Or use a preset:

curl -X POST "https://api.haltless.io/api/v1/settings/api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bi-dashboard",
    "scopes": ["read_only"]
  }'

Response:

{
  "id": "uuid",
  "name": "edge-agent-prod",
  "key": "hlts_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "scopes": ["ingest", "agent"],
  "tenant_id": "uuid",
  "created_at": "2026-04-04T10:00:00Z"
}

warning

The key is returned only once at creation time. Store it securely , you cannot retrieve it later. If lost, revoke the key and create a new one.

Expiration

The expires_at field is optional. If omitted, the key does not expire automatically. Best practice is to always set an expiration and rotate keys periodically.

Using an API key

Pass the key in the X-API-Key header with every request:

curl "https://api.haltless.io/api/v1/machines" \
  -H "X-API-Key: hlts_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

API keys work for all endpoints that accept Bearer JWT authentication. The server resolves the key to its owning tenant and user.

Edge agent configuration

In your edge agent's config.toml:

[haltless]
api_url   = "https://api.haltless.io/api/v1"
api_key   = "hlts_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

Or use an environment variable:

export HALTLESS_API_KEY="hlts_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

Listing keys

View all active keys (secrets are never returned):

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

[
  {
    "id": "uuid",
    "name": "edge-agent-prod",
    "key_prefix": "hlts_a1b2c3",
    "expires_at": "2027-04-04T00:00:00Z",
    "created_at": "2026-04-04T10:00:00Z"
  }
]

Revoking a key

Revoke a key immediately when it is compromised, no longer needed, or being rotated:

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

Revocation is instant. Any request using the revoked key will receive a 401 Unauthorized response.

Key rotation strategy

Rotate API keys regularly to minimize exposure from leaked credentials.

Zero-downtime rotation

1. Create a new key with a descriptive name (e.g., edge-agent-prod-2026-q2)
2. Update your edge agent configuration to use the new key
3. Verify the agent is authenticating with the new key by checking recent audit logs
4. Revoke the old key once you confirm the new key is active

# Step 1: Create new key
curl -X POST "https://api.haltless.io/api/v1/settings/api-keys" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "edge-agent-prod-2026-q2", "expires_at": "2026-10-01T00:00:00Z"}'

# Step 2: Update edge agent config with the new plaintext_key

# Step 3: Verify in audit logs
curl "https://api.haltless.io/api/v1/audit?action=create_api_key&page_size=5" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Step 4: Revoke old key
curl -X DELETE "https://api.haltless.io/api/v1/settings/api-keys/{old_key_id}" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Security best practices

1. Never commit keys to version control. Use environment variables or a secrets manager.
2. Use descriptive names so you can identify which system uses each key.
3. Set expiration dates , quarterly rotation is a good default.
4. Use one key per system , don't share a single key across multiple agents.
5. Monitor the audit log for create_api_key and revoke_api_key events.
6. Revoke immediately if a key is exposed in logs, error messages, or repositories.

Rate limits

API key requests count toward your tenant's rate limits, the same as JWT-authenticated requests. See Rate Limiting for tier-specific limits.

Tier	Write ops/min	Read ops/min
Free	60	300
Pro	300	1,500
Enterprise	1,200	6,000