Skip to main content

API Keys and Rotation

WispHive enforces API key authentication on exposed API endpoints over HTTPS. These credentials are designed for server-to-server use only.

Generation model​

  • Management API keys protect provisioning endpoints such as POST /api/v1/oauth/integrations/* and are sent in X-API-Key.
  • AAA callback keys protect POST /cp/rdt/{callback_slug}/{callback_token} and are sent using X-API-Key or X-WispHive-Token.
  • Clients generate or rotate keys from the WispHive dashboard under Settings → Authentication → API Keys.
  • Full key secrets are shown only when created or rotated; persist them in your own secret manager.
  • Teams that do not want to code against API docs can configure integrations directly from the dashboard UI.
  • API key management is dashboard-only; there are no public API endpoints for key generation, rotation, or revocation.

Request signing​

For management provisioning endpoints:

  • Send X-API-Key: <management-api-key> on every request.

For AAA handoff callbacks:

  • Send the callback key as X-API-Key (preferred) or X-WispHive-Token request header.
  • wisphive_token in JSON body is supported for compatibility.
  • Send an Idempotency-Key header on every POST.
  • Reuse the same Idempotency-Key only when retrying the exact same payload.

Rotation policy​

Recommended practice:

  1. Generate a new key in the dashboard.
  2. Deploy it to your backend.
  3. Validate a callback in a staging flow.
  4. Revoke the previous key.

Security requirements​

  • Treat wisphive_token as a production secret.
  • Never embed it in browser JavaScript.
  • Never log it.
  • Store it only in server-side configuration or a secret manager.