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 on the Control Plane API Keys card under Billing → Overview. 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.

Keys work only while your plan includes the Control Plane API. If your plan stops including it, every control-plane request is refused with 403, whichever key it carries.

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, or using an origin another organization already has, returns 409. A workspace without an active subscription gets 402.

curl -X POST https://hedgehog.com/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://hedgehog.com/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://hedgehog.com/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://hedgehog.com/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 Custom Accounts page. Federated sign-in activates only when the organization is in federated mode, has at least one active signing key, and Custom Accounts has been enabled for your account. Accounts without it stay on Hedgehog login.

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 are refused 300 s after iat
   "exp": 1767139500,        // required
   "email": "ada@example.com" // optional — read only when you map an email claim
}

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://hedgehog.com/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.

The claim contract

Every assertion must carry sub and name, and the 5-minute age limit is fixed, so a user always keeps the same account. On top of those, each organization can map three optional kinds of claim:

• Handle claim — used as the user's handle on their first sign-in when it is free; otherwise the handle comes from the display name.
• Email claim — the user's email, stored unverified and visible only to Hedgehog staff. It never signs anyone in. Clearing the email claim deletes the emails already stored for that organization.
• Custom claims — up to 20 of your own claim names. Their values from each user's latest sign-in are stored as custom attributes you can read back.

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

curl -X PUT https://hedgehog.com/api/control-plane/organizations/Organization:550e8400-e29b-41d4-a716-446655440000/claim-contract \
   -H "Authorization: ControlPlane cpk_AbCdEfGhIjKl.your-secret-part" \
   -H "Content-Type: application/json" \
   -d '{
      "handle_claim": "preferred_username",
      "email_claim": "email",
      "custom_claims": ["plan", "region"]
   }'

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

# → { "account": { … }, "attributes": { "plan": "pro", "region": "eu" } }

The same settings are on each organization's Custom Accounts page in the dashboard. Reading a federated user returns 404 until they have signed in once.

Linking to Hedgehog accounts

When you send an email claim, the person behind a federated account can connect it to their own Hedgehog account. They sign in to Hedgehog directly with that email, or change their Hedgehog email to it, and confirm it with the code we email them. Their federated accounts that carry the address are then linked to their Hedgehog account, in every organization that sent it.

Linking moves no comments and changes nothing about your sign-in: your users keep signing in to the same federated account, and its display name keeps following your assertions. Only the person sees the link, on their own profile, and they can remove it there. A Hedgehog account created by that sign-up takes the federated handle when it is free, and otherwise the handle prefixed with the first word of your organization's name.

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. Revoking a key refuses new sign-ins signed with it, while sessions already created with it keep working until they expire.

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

# → { "list": [ … ], "signingKeys": [ { "kid": "signing-key-2026", "status": "active", … } ] }

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

Destroying an organization

Deleting an organization is a hard, irreversible cascade: comments, reactions, notifications, themes, assets, federated accounts, their stored emails and custom attributes, their links to people's Hedgehog accounts, permissions, and auth settings are all permanently removed. The linked Hedgehog accounts themselves are untouched. There is no undo.

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