Data Models

This reference defines the production request and response models for WispHive-managed OAuth integrations.

Supported entity types

The following registration types can create OAuth integrations:

• sme
• education
• isp_nsp

The registration_id you submit must belong to one of these entity types.

Conventions

• All request and response bodies are JSON.
• All URLs must use https://.
• Empty or whitespace-only string fields are treated as missing.
• Validation failures return HTTP 400.
• Secrets such as OAuth client secrets and callback signing tokens are stored by WispHive but are only shown in plaintext at creation time.

HostedOAuthIntegrationRequest

Used by POST /api/v1/oauth/integrations/hosted.

Field	Type	Required	Description
registration_id	string	Yes	Existing SME, education, or ISP registration ID
entity_name	string	No	Optional display override; defaults to the registered entity name
provider_name	string	Yes	Provider label, e.g. google, microsoft-entra, auth0
provider_domain	string	No	Optional issuer domain override; defaults to the authorize URL hostname
oauth_authorize_url	string (URI)	Yes	Provider authorization endpoint
oauth_token_url	string (URI)	Yes	Provider token endpoint
oauth_jwks_url	string (URI)	Yes	Provider JWKS endpoint
oauth_client_id	string	Yes	Provider-issued client identifier
oauth_client_secret	string	Yes	Provider-issued client secret for confidential flows
oauth_scope	string	No	Defaults to openid profile email
oauth_audience	string	No	Optional audience or API identifier
third_party_provider_url	string (URI)	No	Provider admin or tenant URL
captive_portal_url	string (URI)	No	Optional override; defaults from the registration

Hosted integration response

{
  "success": true,
  "integration": {
    "id": "oi_a83e52a5ffed1d",
    "registration_id": "sme_1ab23cd45ef6",
    "registration_type": "sme",
    "entity_name": "Acme SME",
    "integration_mode": "hosted_oauth",
    "provider_name": "google",
    "callback_url": "https://auth.samwifi.site/oauth/FA2D7/a5e7f-f3a511-2a9fd2",
    "hosted_login_url": "https://auth.samwifi.site/oauth/start/sme_1ab23cd45ef6-4fd388b2",
    "derived_name": "acme-sme-cd45ef",
    "derived_email_domain": "acme-sme-cd45ef.id.wisphive.net",
    "derived_username_format": "acme-sme-cd45ef-{alias}"
  }
}

AAAHandoffIntegrationRequest

Used by POST /api/v1/oauth/integrations/aaa-handoff.

Field	Type	Required	Description
registration_id	string	Yes	Existing SME, education, or ISP registration ID
entity_name	string	No	Optional display override; defaults from the registration
provider_name	string	Yes	Provider label used for auditability
client_oauth_entry_url	string (URI)	Yes	The OAuth login URL your captive portal points to
captive_portal_url	string (URI)	No	Optional override; defaults from the registration
redirect_base_url	string (URI)	No	Optional override; defaults to the WispHive redirect domain

The integration response also includes a WispHive-assigned derived identity namespace and email domain for privacy-safe AAA handoff payloads.

SelfHostedOAuthIntegrationRequest

Used by POST /api/v1/oauth/integrations/self-hosted. It has the same OAuth authorize/token/JWKS/client fields as HostedOAuthIntegrationRequest; the OAuth endpoints are hosted by the client entity while WispHive manages signed state, callbacks, and redirect orchestration.

The persisted integration_mode is self_hosted_oauth, and the response uses self_hosted_login_url.

AAA handoff response

{
  "success": true,
  "integration": {
    "id": "ah_8fa31d4c1b92d0",
    "registration_id": "edu_1ab23cd45ef6",
    "registration_type": "education",
    "entity_name": "North Campus",
    "integration_mode": "aaa_handoff",
    "provider_name": "google",
    "callback_url": "https://auth.samwifi.site/cp/rdt/cp-6a3e91fa6c1b/A29-U1N7W90A",
    "wisphive_token": "WH_Oid-a67d39t78sqcaRedsWte9_Kl90klhgyr37gHgfw-uiDlc35j9yUfa",
    "idempotency_required": true,
    "derived_name": "north-campus-cd45ef",
    "derived_email_domain": "north-campus-cd45ef.id.wisphive.net",
    "derived_username_format": "north-campus-cd45ef-{alias}"
  }
}

AAAHandoffCallbackRequest

Sent by your backend to the callback_url returned when creating an AAA handoff integration.

Field	Type	Required	Description
entity_name	string	Yes	Display name of the authenticated entity
userid	string (UUID)	Yes	Stable user identifier generated by your system
derived_username	string	Yes	Must start with the assigned derived_name prefix, e.g. north-campus-cd45ef-student-001
derived_email	string	Yes	Must use the assigned derived_email_domain, e.g. north-campus-cd45ef-student-001@north-campus-cd45ef.id.wisphive.net
user_session_id	string	Yes	Stable user session identifier for downstream orchestration
wisphive_token	string	Yes*	Signing secret returned when the integration was created

* You may alternatively send the token in the X-WispHive-Token header.

Sensitive direct user fields such as email, display_name, and provider_subject are not accepted in AAA handoff payloads.

Required headers

• Content-Type: application/json
• Idempotency-Key: <unique-value>

AAA callback response

{
  "success": true,
  "integration_id": "ah_8fa31d4c1b92d0",
  "event_id": "1722487101867-0",
  "redirect_url": "https://auth.samwifi.site/openid/cp/gAAAAABo...",
  "expires_in_seconds": 300
}