Skip to main content

Security overview

Constellation OS has two authentication surfaces with different models, both designed to fail closed:

SurfaceCredentialModel
Platform APITenant API key in the x-api-key headerKey is the principal; tenant identity derives from the key, never the hostname
ConsoleCognito sign-in (email and password)User identity for plans, entitlements, and billing

The two are deliberately separate: a console account does not grant API access, and an API key does not sign into the console. A separate operator-only surface (/rules*) uses Cognito identity tokens and is not part of the customer API.

Platform API keys​

Lifecycle, honestly stated​

  • Keys are provisioned per tenant, per environment, by the platform team, and stored in AWS Secrets Manager. There is no self-serve key purchase or mint against the platform today; keys generated locally in the console browser are not registered until provisioned. Getting a key starts with your tenant engagement; see Enterprise.
  • Keys are environment-scoped. A dev key returns 401 on prod, always.
  • The API validates keys against a SHA-256 hash map loaded at startup, and the plaintext key material is scrubbed from the process environment after parsing. Validation adds no measurable latency.
  • Rotation goes through the platform team. Plan for it: read the key from configuration, not from code.

Roadmap, one line: scoped tokens and self-serve key issuance from the console are planned; today the console's key screens generate material that still requires platform-side provisioning.

Lockout​

Failed authentication is tracked per client IP: 5 failures within a 300-second window locks the IP out for 900 seconds, and the lockout gate runs before key verification, so a locked-out IP gets 429 auth_lockout even with a correct key. Each success decays the failure counter by one. The practical rule for clients: treat 401 as fatal and stop, never retry a bad key in a loop, or your gateway locks itself out. Full details: Authentication.

Rate limits and body caps​

Independent of auth, every environment enforces per-IP and per-tenant rate limits, a 1 MB body cap, and a 1,000-record telemetry batch cap, with Retry-After on retryable responses. See Errors and limits.

Console sign-in​

The console authenticates users against Amazon Cognito with an in-app sign-in flow. Sign-in gates plans and entitlements (assistant queries, prediction tiers, live API configuration); guest mode exists deliberately, with the globe and deterministic analytics available and 10 assistant queries. Billing runs through Stripe; the console never sees card details.

Transport​

All hosted surfaces (consoles, platform API, docs) are TLS-only. Browser calls to the platform API are additionally constrained by a per-environment CORS allowlist; when no origins are configured, CORS is off entirely and browsers cannot call the API cross-origin. Build integrations server-side. See API overview.

Key storage guidance​

  • Keep keys in a secrets manager or environment variables (CONSTELLATION_API_TOKEN is the convention); never in source control, never in a browser bundle.
  • The fleet agent's config.toml contains the key in plaintext; keep it mode 0600 on a host with controlled access.
  • Prefixes (cos_live_, cos_dev_, cos_sbx_) identify a key's environment at a glance; use them in incident triage to size blast radius.
  • If a key leaks, contact the platform team for rotation and treat every environment the key's prefix names as exposed.