API Keys

API keys are the primary authentication mechanism for services and automation that send telemetry to InfraSage. They are scoped, rate-limited, and audited.

Key Scopes

Scope	Allowed Operations	Use Case
`ingestion`	`POST /api/v1/telemetry` only	Application agents, CI/CD pipelines sending metrics
`readonly`	All `GET` endpoints	Dashboards, external monitoring tools
`full`	All operations within the tenant	Admin scripts, integration testing

:::tip Principle of least privilege Use ingestion scope keys for your production services. Reserve full scope keys for internal tooling and never commit them to version control. :::

Creating a Key

Requires Admin role or higher.

curl -X POST http://localhost:8080/api/v1/apikeys \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-payment-api-ingestion",
    "scope": "ingestion",
    "rate_limit_rps": 1000,
    "expires_at": "2027-01-01T00:00:00Z"
  }'

Response (key shown only once)

{
  "key_id": "isage_key_abc123",
  "api_key": "isage_ab1c2d3e4f5g6h7i8j9k0l",
  "name": "production-payment-api-ingestion",
  "scope": "ingestion",
  "rate_limit_rps": 1000,
  "expires_at": "2027-01-01T00:00:00Z",
  "created_at": "2026-04-10T12:00:00Z",
  "prefix": "isage_ab..."
}

:::warning Store the key immediately The full API key is returned only at creation time. InfraSage stores only a bcrypt hash of the key. If lost, you must create a new one. :::

Using a Key

Pass the API key in the X-API-Key header:

curl -X POST http://localhost:8080/api/v1/telemetry \
  -H "X-API-Key: isage_ab1c2d3e4f5g6h7i8j9k0l" \
  -H "Content-Type: application/json" \
  -d '{...}'

Listing Keys

curl http://localhost:8080/api/v1/apikeys \
  -H "Authorization: Bearer $ADMIN_JWT"

{
  "keys": [
    {
      "key_id": "isage_key_abc123",
      "name": "production-payment-api-ingestion",
      "prefix": "isage_ab...",
      "scope": "ingestion",
      "rate_limit_rps": 1000,
      "expires_at": "2027-01-01T00:00:00Z",
      "created_at": "2026-04-10T12:00:00Z",
      "last_used_at": "2026-04-10T12:05:30Z"
    }
  ]
}

Revoking a Key

curl -X DELETE http://localhost:8080/api/v1/apikeys/isage_key_abc123 \
  -H "Authorization: Bearer $ADMIN_JWT"

Revocation is immediate. Subsequent requests using the revoked key return HTTP 401.

Rate Limits

Each key has an independent rate limit (requests per second). When the limit is exceeded:

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
  "status": "error",
  "error": "rate_limit_exceeded",
  "message": "Key rate limit: 1000 RPS. Current usage: 1247 RPS."
}

Global tenant rate limits (set by billing plan) apply separately from per-key limits.

Key Rotation Best Practices

Set expires_at to no more than 12 months
Rotate keys quarterly in production
Create the new key first, update your services, then revoke the old key
Use different keys for different services so you can revoke individual services independently
Never share keys between production and staging environments

Key Scopes​

Creating a Key​

Using a Key​

Listing Keys​

Revoking a Key​

Rate Limits​

Key Rotation Best Practices​