Enterprise

Control-plane keys

Control-plane requests authenticate with an API key scoped to your billing group. A billing-group admin creates keys in the dashboard under Billing → API keys. The full secret — in the form <kid>.<secret> — is shown once at creation; only a hash is stored, so copy it immediately. Keys can be revoked at any time from the same page.

Send the key on every control-plane request in the Authorization header with the ControlPlane scheme.

Provisioning organizations

Create one organization per site, tenant, or workspace in your product. The origin is the URL where you'll embed the widgets (it powers CORS and OAuth). Creation counts against your plan's organization limit — exceeding it returns 402, and a conflicting origin returns 409.

curl -X POST https://api.hedgehog.app/api/control-plane/organizations \
   -H "Authorization: ControlPlane cpk_AbCdEfGhIjKl.your-secret-part" \
   -H "Content-Type: application/json" \
   -d '{ "name": "Acme Blog", "origin": "https://blog.acme.com" }'

curl https://api.hedgehog.app/api/control-plane/organizations/Organization:550e8400-e29b-41d4-a716-446655440000 \
   -H "Authorization: ControlPlane cpk_AbCdEfGhIjKl.your-secret-part"

# → { "authMode": "federated", "organization": { … }, "signingKeyIds": ["signing-key-2026"] }

Identity federation

By default, viewers sign in through the widget's built-in OAuth flow (hedgehog mode). In federated mode, your identity provider is the source of truth: your backend signs a short-lived assertion for the current user, exchanges it for a Hedgehog access token, and passes that token to the widget. Hedgehog never sees your users' credentials.

1. Register a signing key — the public key of the keypair your identity provider signs with.
2. Switch the organization to federated mode.
3. Exchange assertions for access tokens at login time.

curl -X POST https://api.hedgehog.app/api/control-plane/organizations/Organization:550e8400-e29b-41d4-a716-446655440000/signing-keys \
   -H "Authorization: ControlPlane cpk_AbCdEfGhIjKl.your-secret-part" \
   -H "Content-Type: application/json" \
   -d '{
      "kid": "signing-key-2026",
      "algorithm": "RS256",
      "publicKey": "-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----"
   }'

curl -X PUT https://api.hedgehog.app/api/control-plane/organizations/Organization:550e8400-e29b-41d4-a716-446655440000/auth-mode \
   -H "Authorization: ControlPlane cpk_AbCdEfGhIjKl.your-secret-part" \
   -H "Content-Type: application/json" \
   -d '{ "authMode": "federated" }'

Both steps are also available in the dashboard on each organization's Federation page. Federated sign-in activates only when the organization is in federated mode, has at least one active signing key, and your plan includes Custom Accounts.

The assertion

An assertion is a compact JWS signed with an asymmetric algorithm — symmetric algorithms and alg: none are rejected. The kid header selects which registered signing key verifies the signature; the key material inside the token itself is never trusted.

// Signed by YOUR identity provider with the private key of a registered signing key
{
   "alg": "RS256",          // header — any of RS256/384/512, PS256/384/512, ES256/384/512, EdDSA
   "kid": "signing-key-2026" // header — selects the registered signing key
}
{
   "sub": "user-42",         // required — your stable external user id
   "name": "Ada Lovelace",   // required — display name shown in widgets
   "iat": 1767139200,        // required — issued-at; assertions expire 300 s after iat by default
   "exp": 1767139500         // required
}

Exchange it for an access token — no other credential is needed; the assertion is the credential. Any verification failure returns an opaque 401 by design, so callers learn nothing about why a forged assertion failed.

curl -X POST https://api.hedgehog.app/api/sessions/federated/Organization:550e8400-e29b-41d4-a716-446655440000 \
   -H "Content-Type: application/json" \
   -d '{ "assertion": "<compact JWS from your identity provider>" }'

# → { "access_token": "…" }   pass it to the widget's token attribute

Accounts are created on first sign-in, keyed deterministically by your sub value and scoped to the organization — the same user always resolves to the same Hedgehog account, and display-name changes sync on each login.

Key rotation

Signing keys rotate by kid: register the new public key under a new kid, start signing assertions with it, then revoke the old key. Multiple keys can be active at once, so rotation needs no downtime. Keys move through active, retiring, and revoked states; only active keys verify assertions.

Destroying an organization

Deleting an organization is a hard, irreversible cascade: comments, reactions, notifications, themes, assets, federated accounts, permissions, and auth settings are all permanently removed. There is no undo.

curl -X DELETE https://api.hedgehog.app/api/control-plane/organizations/Organization:550e8400-e29b-41d4-a716-446655440000 \
   -H "Authorization: ControlPlane cpk_AbCdEfGhIjKl.your-secret-part"