API Keys

API keys are the backend identity for Olyx. Your service uses a key to create traces, execute model calls, poll replays, and read project-scoped operational data.

In the current closed beta, keys are project-scoped. That is intentional: a production key should not create staging traces, and a staging key should not affect production spend.

Key Format

Keys are issued as a two-part token:

ak_<key_id>.<secret>

Part	Purpose
`key_id`	Identifies the key in traces, dashboard tables, and alerts. Safe to display.
`secret`	Authenticates requests. Store it like a password.

The full key is shown once when it is created. After that, dashboard and API responses should only show a masked value.

Key Lifecycle

Treat API keys as operational objects, not random strings copied into servers forever.

flowchart LR CREATE[CREATE KEY] STORE[STORE SECRET] DEPLOY[DEPLOY TO SERVICE] MONITOR[MONITOR USAGE] ROTATE[ROTATE] REVOKE[REVOKE OLD KEY] CREATE --> STORE --> DEPLOY --> MONITOR --> ROTATE --> REVOKE

Stage	What to do
Create	Generate the key in the dashboard for a specific project.
Store	Put the full secret in your secrets manager immediately.
Deploy	Load the key into one service or environment.
Monitor	Watch `last_used`, status, spend, and alert events.
Rotate	Create a replacement, deploy it, verify traffic, then revoke the old key.
Revoke	Stop future requests while preserving historical trace attribution.

Loading Keys in Code

The SDKs attach the key to requests for you. Keep the key in environment configuration or a secrets manager.

import Olyx from "@olyx-labs/olyx";

export const olyx = new Olyx({
  apiKey: process.env.OLYX_API_KEY!,
});

import os
import olyx

olyx.configure(
    api_key=os.environ["OLYX_API_KEY"],
    mock=False,
)

client = olyx.Olyx()

Olyx.configure do |config|
  config.api_key = ENV.fetch("OLYX_API_KEY")
end

client = Olyx.new

Never put an Olyx API key in browser code, mobile clients, public repos, logs, or screenshots. Call Olyx from your backend and let your backend enforce user-level authorization.

Spend Limits

Set a per-key hourly spend cap when a service is new, experimental, or user-facing. If a prompt loop or integration bug starts spending unexpectedly, a key-level cap limits the blast radius.

State	Meaning
`active`	Key can authenticate requests.
`tripped`	Hourly spend cap was reached and the key needs review.
`loop_detected`	Loop protection halted suspicious repeated traffic on that key.

Reset a key only after you understand why it tripped. For production, prefer fixing the service or raising the cap deliberately over repeatedly reactivating the same key.

One Key Per Environment

Use separate keys for each environment and each service that has a different risk profile.

Environment	Suggested key name
Local development	`dev:<service>`
CI	`ci:<service>`
Staging	`staging:<service>`
Production	`prod:<service>`

This makes incidents easier: a cost spike from staging:billing-worker should not require rotating the production API key used by your customer-facing app.

Key Fields Reference

Use these fields when reviewing keys in the dashboard or API reference.

Field	Description
`id`	The `ak_<key_id>` portion.
`name`	Human label for the service or environment.
`masked`	Display-safe key preview.
`project`	Project the key is scoped to.
`status`	`active`, `tripped`, or `loop_detected`.
`hourly_limit`	Optional rolling hourly cap in USD.
`expires_at`	Optional hard expiry timestamp.
`last_used`	Last observed authenticated activity.
`loop_intervention_count`	Number of loop interventions recorded for the key.

The full raw_key is intentionally absent after creation.

Revoking a Key

Revoke a key from the dashboard when it is compromised, retired, or replaced by a rotation.

flowchart TD NEW[CREATE REPLACEMENT KEY] DEPLOY[DEPLOY NEW SECRET] VERIFY[VERIFY TRACE FROM NEW KEY] REVOKE[REVOKE OLD KEY] WATCH[WATCH ERRORS AND LAST USED] NEW --> DEPLOY --> VERIFY --> REVOKE --> WATCH

For production rotation, create and deploy the replacement first. Confirm at least one trace is created by the new key, then revoke the old key.