Skip to content

Manage stream API keys

You will learn how to create, scope, rotate, and revoke bounded stream ingest API keys.

Stream API keys (lax_…) authenticate ingest only. They cannot query or manage the app. Session JWTs and personal access tokens cannot ingest.

You need the Ingest keys stream role or higher. Workspace owners and admins already have this. A workspace member on a Workspace-visible stream only has Query unless someone raises their stream role on Members.

Create a key

  1. Select the target stream in the sidebar.
  2. Open Streams.
  3. Under API keys, click New API key.
  4. Enter a Name (for example do-app-platform or local-curl).
  5. Optionally choose an earlier Expires time. Standard Cordo defaults to 90 days; operators can lower that default and the one-year maximum.
  6. Select only the ingest surfaces this collector needs:
  7. Native HTTP — JSON and plain-text stream endpoints
  8. OTLP Logs
  9. OpenSearch
  10. Optionally set an Events per minute ceiling. The stricter of this value and the server-wide key limit wins.
  11. Click Create key.
  12. Copy the secret from Save this API key — it is shown only once. Confirm that you saved it before closing the dialog.

Also copy the ready-made curl sample when present; it already includes your API host, stream id, and key.

Use the key

Path How to send the key
Native HTTP JSON Header X-API-Key: lax_…
Native HTTP plain text Header X-API-Key: lax_… on /ingest/text
OpenSearch-compatible _bulk HTTP Basic — username ignored; password = API key
OTLP Logs X-API-Key or Authorization: Bearer lax_…

Native first-run example:

curl -sS -X POST "$CORDO_API/v1/streams/$STREAM_ID/ingest" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $KEY" \
  -d '{"level":"info","msg":"hello from curl"}'

Full method guides: Ingest your logs.

Check key health

The API keys table shows Name, Access, Expires, Last used, and Health. Lifecycle states are:

  • Active — accepted on its selected ingest surfaces.
  • Grace period — a rotated predecessor remains accepted until the shown cutover time.
  • Superseded — its overlap ended; use the successor.
  • Expired — its lifetime ended.
  • Revoked — manually disabled.

Active keys can also warn:

  • Stale — not used within the deployment's stale window (seven days by default), including a new key left unused for that long.
  • Expiring soon — expires within the deployment's warning window (seven days by default).
  • Rate-limit activity — recently exceeded a per-key ingest budget. This is an explainable anomalous-use signal; check the collector before raising its limit.

Last used is debounced, so allow about 30 seconds for recent activity to appear.

Rotate safely

  1. Click Rotate on the key being replaced.
  2. Keep the standard 300-second overlap, shorten it for faster cutover, or use 0 only when the collector can switch immediately.
  3. Click Rotate key and copy the new secret from the one-time dialog.
  4. Update the collector during the overlap. The old secret stops authenticating when the grace period ends; the successor receives the deployment's default lifetime (90 days in standard Cordo).

Only one successor can be minted from a key. If a rotation response is lost, rotate the active successor or create a new key rather than retrying the old key blindly.

Revoke immediately

To revoke:

  1. Click Revoke on an active key.
  2. Confirm. Ingest with that secret stops immediately.

You cannot recover a revoked secret. Revoking a predecessor also ends any remaining overlap immediately; it does not revoke its successor. Revoking a successor does not restore its predecessor, so deploy another active key before the predecessor's grace period ends.

Next