API Keys

API keys are the recommended authentication method for server-to-server calls including event ingestion, membership checks, and automation scripts.

Two Auth Modes#

SegOps supports two authentication modes:

• JWT (Bearer token) — short-lived (60 min), obtained by logging in with email/password. Best for user-facing API calls from your frontend or authenticated sessions. Requires periodic refresh.
• API Key (ApiKey header) — long-lived, tenant-scoped credentials. Best for server-to-server calls, CI/CD pipelines, and production event ingestion. Keys do not expire automatically — revoke them explicitly when no longer needed.

Creating an API Key#

1. Navigate to Settings → API Keys
2. Click + New Key
3. Enter a descriptive name (e.g., “Production Ingestor”)
4. Click Create and copy the key immediately — it is shown only once

Or via the API (requires a JWT):

curl -X POST https://api.segops.ai/api/auth/api-keys/ \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Ingestor",
    "tenant_slug": "acme"
  }'

# Response (key shown once — store it immediately):
# { "id": 5, "name": "Production Ingestor", "key": "sk_live_xxxxx..." }

Key Format#

All API keys start with sk_(for “secret key”). In API calls, pass the key in the Authorization header as:

Authorization: ApiKey sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Revoking Keys#

Revoke a key from Settings → API Keys by clicking the trash icon next to the key. Revocation is immediate — the key will return 401 on its next use.

curl -X DELETE https://api.segops.ai/api/auth/api-keys/5/ \
  -H "Authorization: Bearer $JWT"

Security Best Practices#

• Never expose keys client-side — do not include API keys in browser JavaScript bundles, React components, or mobile app binaries where they can be extracted.
• Store in secrets managers — use environment variables, AWS Secrets Manager, GCP Secret Manager, or Vault. Never commit keys to source control.
• Use separate keys per environment — create distinct keys for development, staging, and production. This makes rotation safer and limits blast radius.
• Rotate regularly — revoke and re-create keys every 90 days, or immediately after any suspected exposure.
• Audit key names — use descriptive names so you know exactly which service uses each key when you need to rotate or revoke it.