Skip to main content
Onchain Suite uses two kinds of key. The live / test segment is the environment. Publishable keys only authenticate the SDK’s challenge/verify flow; everything that sends or reads data uses a secret key.
The quick mental model. A publishable key is like your street address, fine for anyone to see; it only lets a browser start the wallet sign-in. A secret key is like your house key: it opens everything, so it lives only on your server and never ships to a browser or a public repo.

​
Secret keys

A secret key looks like sk_live_<keyId>.<verifier>. Only a hash of the verifier is stored; the full key is shown once, at creation, and can’t be retrieved afterward. If you lose it, roll it. Each key carries a scope:
  • Read/write (default): full server-to-server access.
  • Read-only: reads only, for reporting or export integrations.
Creating, rolling, and revoking secret keys is limited to OWNER and ADMIN, and the number of keys is capped by your plan.

​
Rolling a key

Rolling issues a replacement and schedules the old key to stop working after a grace period you choose (up to 7 days), so you can redeploy before the old one dies. The replacement keeps the same name, scope, and environment, and doesn’t count against your plan’s key limit, so a leaked key can always be replaced.
  • Leaked key: roll with a zero grace period to kill it immediately.
  • Planned rotation: roll with a grace window (say 24–72 hours), deploy the new key, and let the old one expire on its own.
Revoking a key removes it outright.
Treat a secret key like a password. Keep it in server-side configuration or a secrets manager, never in frontend code, a repo, or a browser. If one is exposed, roll it with zero grace immediately.

​
Publishable keys

Publishable keys are embedded in your dApp’s page source on purpose. They only permit the wallet challenge/verify handshake, scoped to your allowed origins. They’re protected by your origin allowlist, not by secrecy, so shipping one is fine. Put a publishable key in NEXT_PUBLIC_ONCHAIN_PK (or your framework’s public-env equivalent); never put a secret key there. The key environment maps to an origin bucket, and they have to match:

​
Getting and rotating a publishable key

Your keys are shown in the dashboard, and can also be read over the API. Unlike a secret key, a publishable key is shown in full every time; it isn’t secret.
Rotating a publishable key has no grace period: because it lives in your page source, clients pick up the new key on their next deploy. See In-App Notifications for how it’s used.

​
Server-to-server endpoints

A secret key unlocks a small, deliberate set of endpoints built for protocols integrating from their own backend. Base path https://api.onchainsuite.com/api/v1, authenticated with Authorization: Bearer sk_live_…. Three more server-to-server entry points are documented elsewhere: POST /events for custom events, POST /inapp/push for direct pushes, and the Automation Trigger API for feeding trigger events. You can also register outbound webhooks to receive events from the platform; the signing secret is shown once when you create the webhook.

​
Practices that hold up

  • Keep secret keys server-side only.
  • Use a read-only key for anything that only reports or exports.
  • Use test keys in non-production environments.
  • Roll on a schedule, and roll with zero grace the moment a key might be exposed.
  • Remove keys you no longer use.