How to Integrate Retool with Okta

Okta's REST API uses SSWS (session) tokens for authentication. Unlike OAuth 2.0 client credentials, SSWS tokens are static tokens tied to the admin account that created them and inherit that account's permissions. To create one, log in to your Okta Admin Console (yourcompany.okta.com/admin/dashboard) with Super Administrator or appropriate admin role. Navigate to Security in the top navigation, then select API from the dropdown. On the API page, click the Tokens tab. Click Create Token. Enter a token name like 'Retool Integration' and click Create Token. Okta displays the token value once — copy it immediately, as it cannot be retrieved again after you close the dialog. This token is an alphanumeric string prefixed with '00' in Okta's format. Store this token in Retool as a Configuration Variable (Settings → Configuration Variables) named OKTA_API_TOKEN marked as a secret. Also store your Okta domain as OKTA_DOMAIN (e.g., yourcompany.okta.com without https://). Best practice: create a dedicated Okta service account (a system admin account that does not belong to a real person) to generate the API token. This prevents the token from being invalidated if the individual admin account is deactivated. Assign the service account the 'Read-Only Administrator' role for read-only dashboards, or 'Organization Administrator' for panels that perform user management operations.

With the SSWS token ready, create the Okta REST API Resource. Navigate to Resources in the left sidebar and click Add Resource. Select REST API. Name the resource 'Okta API'. Set Base URL to https://{{ retoolContext.configVars.OKTA_DOMAIN }}/api/v1 — this constructs the base URL dynamically from the Configuration Variable. Under Authentication, select Header Auth. Add the Authorization header with value SSWS {{ retoolContext.configVars.OKTA_API_TOKEN }} — note the space between 'SSWS' and the token value, and the space between the two parts of the value is required. Unlike Bearer token auth, Okta uses the 'SSWS' prefix in the Authorization header rather than 'Bearer'. Add a second default header Accept: application/json. Click Save and create a test query: GET /users?limit=1 against the Okta API resource. A successful response returns a JSON array with one user object containing profile, credentials, and status fields. If you see 401, verify the Authorization header format is exactly 'SSWS {token}' with no extra characters. If you see 403, the service account creating the token may lack the required Okta admin role.

Create the core user management queries. First, 'searchOktaUsers': GET /users. Add URL parameters: q → {{ userSearchInput.value || '' }} (Okta's q parameter searches across firstName, lastName, and email), limit → {{ pagination.pageSize || 25 }}, after → {{ pagination.cursor || '' }} (cursor-based pagination using the 'after' parameter from Link headers). Okta returns user objects with profile (firstName, lastName, email, login, department, title), status (ACTIVE, DEPROVISIONED, SUSPENDED, PASSWORD_EXPIRED, LOCKED_OUT, RECOVERY), and created/lastLogin timestamps. Create a transformer that normalizes this into flat objects for the Table. Create these additional mutation queries: 'deactivateUser' — POST /users/{{ usersTable.selectedRow.id }}/lifecycle/deactivate (suspends Okta access for all connected apps). 'activateUser' — POST /users/{{ usersTable.selectedRow.id }}/lifecycle/activate with query param sendEmail=true. 'unlockUser' — POST /users/{{ usersTable.selectedRow.id }}/lifecycle/unlock. 'resetPassword' — POST /users/{{ usersTable.selectedRow.id }}/lifecycle/reset_password?sendEmail=true. 'expireSessions' — DELETE /users/{{ usersTable.selectedRow.id }}/sessions (terminates all active sessions immediately). Create a 'getUserGroups' query: GET /users/{{ usersTable.selectedRow.id }}/groups to show group memberships for the selected user.

1// Transformer: normalize Okta user list for Retool Table
2const users = Array.isArray(data) ? data : [];
3return users.map(user => ({
4  id: user.id,
5  email: user.profile?.email || user.profile?.login || 'N/A',
6  first_name: user.profile?.firstName || '',
7  last_name: user.profile?.lastName || '',
8  display_name: `${user.profile?.firstName || ''} ${user.profile?.lastName || ''}`.trim() || 'Unknown',
9  department: user.profile?.department || '',
10  title: user.profile?.title || '',
11  status: user.status,
12  status_color: {
13    ACTIVE: 'green', SUSPENDED: 'orange', DEPROVISIONED: 'red',
14    LOCKED_OUT: 'red', PASSWORD_EXPIRED: 'yellow', RECOVERY: 'yellow'
15  }[user.status] || 'gray',
16  last_login: user.lastLogin
17    ? new Date(user.lastLogin).toLocaleString()
18    : 'Never',
19  created: new Date(user.created).toLocaleDateString()
20}));

With working queries, build the user management dashboard. Add a Text Input named 'userSearchInput' at the top of the canvas with a Search button that triggers searchOktaUsers. Add a Table component named 'usersTable' bound to {{ searchOktaUsers.data }}. Configure columns: display_name, email, department, title, status (with a colored Tag using the status_color field from the transformer — green for ACTIVE, orange for SUSPENDED, red for DEPROVISIONED or LOCKED_OUT), and last_login. Enable row selection on the table. To the right of the table, add a user detail Container visible only when a row is selected ({{ usersTable.selectedRow !== null }}). Inside the Container, display the selected user's full details using Text components. Add an Action Buttons section with the lifecycle controls — each button has confirmation logic: 'Deactivate Account' (red button, shows Modal: 'This will remove SSO access to all Okta-connected applications for {{ usersTable.selectedRow.display_name }}. Proceed?'), 'Reset Password' (triggers resetPassword query, shows success notification), 'Unlock Account' (visible only when status is LOCKED_OUT), 'Expire Sessions' (logs the user out of all active sessions immediately). Below the user details, add a Groups sub-Table showing the user's current group memberships from getUserGroups, with group name and description. Add a 'Remove from Group' button for each group row that triggers DELETE /groups/{groupId}/users/{userId}.

1// Query config for removing a user from an Okta group
2// DELETE /groups/{groupId}/users/{userId}
3// Path: /groups/{{ usersTable.selectedRow.selectedGroupId }}/users/{{ usersTable.selectedRow.id }}
4// Method: DELETE
5// No body required for DELETE operations
6// On success: trigger getUserGroups to refresh the group membership list

Create a security monitoring view using Okta's System Log API (GET /logs). The System Log is the authoritative audit trail for all Okta events — user authentications, admin operations, application access, and policy changes. Create a query 'getSystemLog'. Set Method to GET, Path to /logs. Add URL parameters: filter → {{ logEventFilter.value || 'eventType eq "user.session.start"' }}, limit → {{ logPagination.pageSize || 100 }}, since → {{ new Date(Date.now() - 24*60*60*1000).toISOString() }}, until → {{ new Date().toISOString() }}. The filter parameter uses Okta's SCIM filter syntax. Common event type filters: 'eventType eq "user.authentication.auth_via_IDP"' for SSO logins, 'eventType sw "user.authentication"' for all auth events, 'eventType sw "user.lifecycle"' for user management operations, 'eventType sw "app.oauth2"' for API access events, 'severity eq "WARN" or severity eq "ERROR"' for security alerts. Create a transformer that normalizes log entries: extract eventType, displayMessage, severity (INFO/WARN/ERROR), actor (the user who performed the action), target (the affected resource), client IP, and timestamp. Display in a Table with severity color coding (ERROR = red, WARN = orange, INFO = gray). Add a Bar Chart above the table showing event count by hour for the selected time range, using a GROUP BY hour transformation over the log data. Add a Select component for event type filter with pre-set options for common security event types.

1// Transformer: normalize Okta System Log entries
2const events = Array.isArray(data) ? data : [];
3return events.map(event => ({
4  timestamp: new Date(event.published).toLocaleString(),
5  event_type: event.eventType,
6  display_message: event.displayMessage,
7  severity: event.severity,
8  actor_name: event.actor?.displayName || event.actor?.alternateId || 'System',
9  actor_type: event.actor?.type || '',
10  target: event.target?.[0]?.displayName || event.target?.[0]?.alternateId || '',
11  client_ip: event.client?.ipAddress || 'N/A',
12  geo_location: event.client?.geographicalContext
13    ? `${event.client.geographicalContext.city}, ${event.client.geographicalContext.country}`
14    : 'Unknown',
15  outcome: event.outcome?.result || '',
16  reason: event.outcome?.reason || ''
17}));