Skip to main content

Designing OAuth Endpoints for Server-to-Server Calls

This guide captures the software-engineering principles WispHive expects integrators to follow when they POST authenticated users back to the platform or provision OAuth integrations programmatically.

Design principles​

  1. Use stable, versioned URLs
    • Prefer /api/v1/... contracts for provisioning APIs.
  2. Keep browser and server responsibilities separate
    • Browsers use GET /oauth/start/{integration_id}.
    • Backends use signed callback POSTs to the returned callback_url.
  3. Require idempotency on write operations
    • All callback POSTs must provide Idempotency-Key.
  4. Protect all secrets server-side
    • OAuth client secrets and wisphive_token values must never be exposed in browser code.
  5. Use strict URL validation
    • Only https:// endpoints are accepted.

Your backend should:

  • Authenticate the user with your chosen IdP.
  • Produce a stable UUID for the user.
  • POST the result to the WispHive callback URL.
  • Preserve the same Idempotency-Key when retrying the same callback.

Retry guidance​

  • Retry 503 responses with exponential backoff and jitter.
  • Do not retry 400 responses unchanged.
  • Reuse the same Idempotency-Key only when the payload is byte-for-byte equivalent.

Example callback request​

curl -X POST "https://auth.samwifi.site/cp/rdt/cp-6a3e91fa6c1b/A29-U1N7W90A" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5ec5f2b1-6f9e-46a4-b5de-37f00d16fb41" \
  -d '{
    "entity_name": "Acme SME",
    "userid": "4d57d5f0-b73f-4d84-b5d2-a06d7701f931",
    "display_name": "Jane Doe",
    "email": "jane@example.com",
    "provider_subject": "google-oauth2|103918273645",
    "wisphive_token": "WH_Oid-a67d39t78sqcaRedsWte9_Kl90klhgyr37gHgfw-uiDlc35j9yUfa"
  }'