Skip to main content

Security Guide

Keep feature flags from leaking into browsers, treat client context as untrusted, and verify signed payloads.

This page is a playbook for app keys and SDK trust. For certifications, data residency, and RBAC, start with the Security & Compliance overview. For audit logs and retention, see Audit & Compliance.

Client vs server keys​

Generate keys from App Settings. Pick the type that matches where the SDK runs:

  • Backend keys: Full flag definitions for the environment. Use only in trusted server code. Store them in environment variables, not in frontend bundles.
  • Front-end keys: Public to the browser or mobile app. They only receive flags you mark Available to Client SDK. Restrict the key to the environments it should serve, and set allowed origins for browser use.
Do not ship a backend key to the client

A Front-end App Key is still a public credential. Treat it as visible. Never put a backend or management key in client configuration.

Available to Client SDK​

Internal flags stay off the public definitions channel until you opt them in.

  1. Open the feature in Features
  2. Enable Available to Client SDK only for flags the browser or mobile app must evaluate
  3. Leave admin, billing, and other sensitive gates unmarked so they never reach a Front-end key

Flags without this mark are omitted from client SDK payloads (including CSS token files). Server SDKs using a backend key still see the full set.

Signed definitions​

Server SDKs can download signed definitions (ECDSA / ES256) from definitions-signed and verify the envelope against Toggly JWKS before evaluating locally.

Enable signature verification in the SDK (UseSignedDefinitions / use_signed_definitions / equivalent). Optionally whitelist AllowedKeyIds. On verification failure, keep last-known-good flags — do not apply an unverified payload.

Evaluated-signed trust​

Client SDKs fetch pre-evaluated booleans from the evaluated-signed worker. That channel is for feature rollout, not authorization.

  • Identity (u / userId), groups, and claims are chosen in the browser. Anyone can change the request.
  • Do not treat client-supplied headers or query parameters as proof of identity. The worker does not validate JWTs or server sessions on these public endpoints.
  • Use opaque IDs and coarse claims (role, plan, beta). Keep PII and tokens off the query string.
  • Enforce admin UI, billing, and security-sensitive APIs on your backend with authenticated context.

Dashboard SSO​

Enterprise SSO (SAML 2.0 and OIDC) is configured by Toggly support — it is not a self-serve dashboard wizard.

To set it up, contact support at [email protected] with your IdP metadata (or OIDC issuer, client ID, and secret), organization name, and email domains. After support enables it, test in a private window at https://app.toggly.io.

Best Practices​

  1. Split keys: Front-end key in the browser, backend key only on the server
  2. Opt in client flags: Mark Available to Client SDK per flag, not by default
  3. Verify signatures: Enable signed definitions in production SDKs
  4. Fail closed on the server: Gate sensitive actions in authenticated backend code
  5. Review access: Use audit logs to inspect flag and permission changes

Next Steps​