UI events from the embedded admin portal

Learn how to listen for and handle UI events from the embedded admin portal, such as SSO connection status and session expiration.

The embedded admin portal emits browser events that allow your application to respond to configuration changes made by organization admins. Use these events to provide real-time feedback, update your UI, sync configuration state, or trigger workflows in your application.

Common use cases include displaying success notifications when SSO is configured, refreshing authentication settings after directory sync is enabled, or prompting users to re-authenticate when their admin portal session expires.

Listening to admin portal events

Add an event listener to your parent window to receive events from the embedded admin portal iframe:

1
window.addEventListener('message', (event) => {
2
  // Security: Always validate the event origin matches your Scalekit environment
3
  if (event.origin !== 'https://your-env.scalekit.com') {
4
    return; // Ignore events from untrusted sources
5
  }
6

7
  // Check if this is a valid admin portal event
8
  if (event.data && event.data.event_type) {
9
    const { event_type, organization_id, data } = event.data;
10

11
    // Handle specific event types
12
    switch (event_type) {
13
      case 'ORGANIZATION_SSO_ENABLED':
14
        // Show success notification, refresh SSO settings, etc.
15
        showNotification('SSO enabled successfully');
16
        break;
17

18
      case 'PORTAL_SESSION_EXPIRY':
19
        // Prompt user to refresh the admin portal
20
        promptSessionRefresh();
21
        break;
22

23
      default:
24
        console.log('Received event:', event.data);
25
    }
26
  }
27
});

SSO events

`ORGANIZATION_SSO_ENABLED`

Fires when an organization admin successfully enables a Single Sign-On connection in the admin portal.

1
{
2
  "event_type": "ORGANIZATION_SSO_ENABLED",
3
  "object": "connection",
4
  "organization_id": "org_4010340X34236531", // Organization that enabled SSO
5
  "message": "Single sign-on connection enabled successfully",
6
  "data": {
7
      "connection_type": "SSO",
8
      "id": "conn_4256075523X312", // Connection ID for API calls
9
      "type": "OIDC", // Protocol: OIDC or SAML
10
      "provider": "OKTA", // Identity provider configured
11
      "enabled": true
12
  }
13
}

Field	Type	Description
`event_type`	string	The type of event being triggered
`object`	string	The object type associated with the event
`organization_id`	string	Unique identifier for the organization
`message`	string	Human-readable message describing the event
`data.connection_type`	string	Type of connection (SSO)
`data.id`	string	Unique identifier for the connection
`data.type`	string	Protocol type (e.g., OIDC, SAML)
`data.provider`	string	Identity provider name
`data.enabled`	boolean	Indicates if the connection is enabled

`ORGANIZATION_SSO_DISABLED`

Fires when an organization admin disables their Single Sign-On connection in the admin portal.

1
{
2
   "event_type": "ORGANIZATION_SSO_DISABLED",
3
   "object": "connection",
4
   "organization_id": "org_4010340X34236531", // Organization that disabled SSO
5
   "message": "Single sign-on connection disabled successfully",
6
   "data": {
7
      "connection_type": "SSO",
8
      "id": "conn_4256075523X312", // Connection ID that was disabled
9
      "type": "OIDC", // Protocol: OIDC or SAML
10
      "provider": "OKTA", // Identity provider that was configured
11
      "enabled": false
12
   }
13
}

Field	Type	Description
`event_type`	string	The type of event being triggered
`object`	string	The object type associated with the event
`organization_id`	string	Unique identifier for the organization
`message`	string	Human-readable message describing the event
`data.connection_type`	string	Type of connection (SSO)
`data.id`	string	Unique identifier for the connection
`data.type`	string	Protocol type (e.g., OIDC, SAML)
`data.provider`	string	Identity provider name
`data.enabled`	boolean	Indicates if the connection is enabled

Session events

`PORTAL_SESSION_WARNING`

Fires when the admin portal session is about to expire (typically 5 minutes before expiration). Use this to prompt users to save their work or refresh their session.

1
{
2
  "event_type": "PORTAL_SESSION_WARNING",
3
  "object": "session",
4
  "message": "The admin portal session will expire in 5 minutes",
5
  "organization_id": "org_43982563588440584",
6
  "data": {
7
    "expiry": "2025-02-28T12:40:35.911Z" // ISO 8601 timestamp when session expires
8
  }
9
}

Field	Type	Description
`event_type`	string	The type of event being triggered
`object`	string	The object type associated with the event
`organization_id`	string	Unique identifier for the organization
`message`	string	Human-readable message describing the event
`data.expiry`	string	ISO 8601 timestamp indicating when the session will expire

`PORTAL_SESSION_EXPIRY`

Fires when the admin portal session has expired. Use this to hide the admin portal iframe and prompt users to re-authenticate.

1
{
2
  "event_type": "PORTAL_SESSION_EXPIRY",
3
  "object": "session",
4
  "message": "The admin portal session has expired",
5
  "organization_id": "org_43982563588440584",
6
  "data": {
7
    "expiry": "2025-02-28T12:40:35.911Z" // ISO 8601 timestamp when session expired
8
  }
9
}

Field	Type	Description
`event_type`	string	The type of event being triggered
`object`	string	The object type associated with the event
`organization_id`	string	Unique identifier for the organization
`message`	string	Human-readable message describing the event
`data.expiry`	string	ISO 8601 timestamp indicating when the session expired

Directory events

`ORGANIZATION_DIRECTORY_ENABLED`

Fires when an organization admin successfully configures and enables SCIM directory provisioning in the admin portal.

1
{
2
    "event_type": "ORGANIZATION_DIRECTORY_ENABLED",
3
    "object": "directory",
4
    "organization_id": "org_45716217859670289", // Organization that enabled directory sync
5
    "message": "SCIM Provisioning enabled successfully",
6
    "data": {
7
        "directory_type": "SCIM", // Directory protocol type
8
        "id": "dir_45716228982964495", // Directory connection ID for API calls
9
        "provider": "MICROSOFT_AD", // Identity provider: OKTA, AZURE_AD, GOOGLE, etc.
10
        "enabled": true
11
    }
12
}

Field	Type	Description
`event_type`	string	The type of event being triggered
`object`	string	The object type associated with the event
`organization_id`	string	Unique identifier for the organization
`message`	string	Human-readable message describing the event
`data.directory_type`	string	Type of directory synchronization (SCIM)
`data.id`	string	Unique identifier for the directory connection
`data.provider`	string	Identity provider name
`data.enabled`	boolean	Indicates if the directory sync is enabled

`ORGANIZATION_DIRECTORY_DISABLED`

Fires when an organization admin disables SCIM directory provisioning in the admin portal.

1
{
2
    "event_type": "ORGANIZATION_DIRECTORY_DISABLED",
3
    "object": "directory",
4
    "organization_id": "org_45716217859670289", // Organization that disabled directory sync
5
    "message": "SCIM Provisioning disabled successfully",
6
    "data": {
7
        "directory_type": "SCIM", // Directory protocol type
8
        "id": "dir_45716228982964495", // Directory connection ID that was disabled
9
        "provider": "MICROSOFT_AD", // Identity provider that was configured
10
        "enabled": false
11
    }
12
}

Field	Type	Description
`event_type`	string	The type of event being triggered
`object`	string	The object type associated with the event
`organization_id`	string	Unique identifier for the organization
`message`	string	Human-readable message describing the event
`data.directory_type`	string	Type of directory synchronization (SCIM)
`data.id`	string	Unique identifier for the directory connection
`data.provider`	string	Identity provider name
`data.enabled`	boolean	Indicates if the directory sync is enabled

Complete event handler Example

Here’s a complete example showing how to handle all admin portal events in a production application:

1
// Initialize event handling for the admin portal
2
function initAdminPortalEventHandling(scalekitEnvironmentUrl) {
3
  window.addEventListener('message', (event) => {
4
    // Security: Validate event origin
5
    if (event.origin !== scalekitEnvironmentUrl) {
6
      return;
7
    }
8

9
    if (!event.data || !event.data.event_type) {
10
      return;
11
    }
12

13
    const { event_type, organization_id, data, message } = event.data;
14

15
    // Log all events for debugging
16
    console.log('[Admin Portal Event]', { event_type, organization_id, data });
17

18
    switch (event_type) {
19
      case 'ORGANIZATION_SSO_ENABLED':
20
        handleSSOEnabled(organization_id, data);
21
        break;
22

23
      case 'ORGANIZATION_SSO_DISABLED':
24
        handleSSODisabled(organization_id, data);
25
        break;
26

27
      case 'ORGANIZATION_DIRECTORY_ENABLED':
28
        handleDirectoryEnabled(organization_id, data);
29
        break;
30

31
      case 'ORGANIZATION_DIRECTORY_DISABLED':
32
        handleDirectoryDisabled(organization_id, data);
33
        break;
34

35
      case 'PORTAL_SESSION_WARNING':
36
        handleSessionWarning(data.expiry);
37
        break;
38

39
      case 'PORTAL_SESSION_EXPIRY':
40
        handleSessionExpiry();
41
        break;
42

43
      default:
44
        console.warn('Unknown event type:', event_type);
45
    }
46
  });
47
}
48

49
function handleSSOEnabled(orgId, data) {
50
  // Show success notification
51
  showToast('success', `SSO enabled successfully with ${data.provider}`);
52

53
  // Sync configuration to your backend
54
  fetch('/api/organizations/${orgId}/sync-sso', {
55
    method: 'POST',
56
    headers: { 'Content-Type': 'application/json' },
57
    body: JSON.stringify({ connectionId: data.id, provider: data.provider })
58
  });
59

60
  // Update UI to reflect SSO is active
61
  updateOrganizationUI(orgId, { ssoEnabled: true });
62
}
63

64
function handleSessionWarning(expiryTime) {
65
  const expiryDate = new Date(expiryTime);
66
  const minutesLeft = Math.round((expiryDate - new Date()) / 60000);
67

68
  showNotification({
69
    type: 'warning',
70
    message: `Your admin session will expire in ${minutesLeft} minutes`,
71
    action: {
72
      label: 'Refresh Session',
73
      onClick: () => window.location.reload()
74
    }
75
  });
76
}
77

78
function handleSessionExpiry() {
79
  // Hide the admin portal iframe
80
  document.getElementById('admin-portal-iframe').style.display = 'none';
81

82
  // Show message to user
83
  showModal({
84
    title: 'Session Expired',
85
    message: 'Your admin portal session has expired. Please refresh to continue.',
86
    action: {
87
      label: 'Refresh Page',
88
      onClick: () => window.location.reload()
89
    }
90
  });
91
}
92

93
// Initialize when your app loads
94
initAdminPortalEventHandling('https://your-env.scalekit.com');