Skip to main content

Signed definitions

For stronger integrity guarantees, Toggly can return signed feature definitions.

When enabled, the SDK:

  • fetches signed definitions from GET https://definitions.toggly.io/definitions-signed/{appKey}/{environment}
  • fetches the JSON Web Key Set (JWKS) from GET https://definitions.toggly.io/.well-known/jwks
  • verifies the signature using ES256 (double SHA-256 over <raw defs json>|<timestamp>, ECDSA P-256)
  • only then applies definitions locally
  • persists signed_defs_json (exact server defs bytes) on snapshots for re-verification

Enable signed definitions​

from toggly import TogglyClient, TogglyConfig

config = TogglyConfig(
    app_key="YOUR_APP_KEY",
    environment="Production",
    use_signed_definitions=True,
)
client = TogglyClient(config)
client.init()

Pin accepted key IDs (KIDs) with allowed_key_ids:

config = TogglyConfig(
    app_key="YOUR_APP_KEY",
    environment="Production",
    use_signed_definitions=True,
    allowed_key_ids=["ABCDEF...ES256"],
)

None or an empty list allows any kid present in JWKS.

How verification works (high level)​

The server signs the payload using the exact JSON bytes of defs plus a timestamp:

  • payload: <raw defs json>|<timestamp>
  • hash: SHA-256 (double)
  • signature: ES256 (ECDSA P-256), IEEE P1363 or DER

The SDK preserves raw JSON for the defs field so the signature matches what the server produced. See Server-side reliability and Caching.

Framework settings​

FrameworkSetting
DjangoTOGGLY["USE_SIGNED_DEFINITIONS"] = True
Flaskapp.config["TOGGLY_USE_SIGNED_DEFINITIONS"] = True
FastAPIconfigure_toggly(..., use_signed_definitions=True) or pass a pre-built TogglyClient