Skip to Content
GuidesSecurity

Security

Secrets

Rotate and store securely:

  • API keys (database-backed, scoped) — create via Settings or POST /v1/keys/new
  • GREENLIGHT_API_KEY — seeds the first admin key when api_keys is empty; UI sends it as X-API-Key
  • AUTH_SECRET — UI sessions
  • CALLBACK_SIGNING_SECRET — prompt callback HMAC
  • WEBHOOK_SECRET — platform webhook verification
  • Per-channel platform credentials in the database

Auth recommendations

  • Production: USE_AUTH=true
  • Use scoped keys (agent, readonly) for automation; reserve admin for operators
  • Prefer API-only mode when you do not need the Admin UI

Callback URL validation

Prompt and channel callback_url values are validated (HTTP/HTTPS). Private / link-local targets are rejected to reduce SSRF risk. Docker setups may rewrite host.docker.internal for local agent callbacks — treat that as a development convenience, not a production pattern.

Signature verification

Always verify X-Signature on prompt answer callbacks. Channel message.created events are unsigned — authenticate those endpoints yourself (VPN, mTLS, shared secret header, etc.).

Media paths

media_path must resolve under MEDIA_ALLOWED_DIR. Uploads are size-capped by MAX_MEDIA_SIZE_MB.

Licensing boundaries

Community self-host is allowed under BUSL-1.1. Selling Greenlight as a competing hosted subscription is not. See Licensing.

Edition roadmap

Community edition stores scoped API keys and api_key_id on outbound messages. Enterprise and Cloud add organization boundaries and fuller audit:

  • Org scope — organization_id on keys, channels, prompts, and messages so a key or session cannot cross tenants (required for Cloud; enterprise uses one invisible org).
  • Dual actors — distinguish API key actions from human user actions (UI should not rely on a shared admin service key long term).
  • Audit events — append-only log: org, actor type/id, action, resource, timestamp (not only api_key_id on message rows).

See Editions & admin identity for how admin setup differs per edition.

ArchitectureTroubleshooting