WorkOS setup - Configview Support

ConfigView reads your WorkOS environment through the WorkOS API, using an API key that a WorkOS admin copies from the WorkOS dashboard. ConfigView only reads. You will end up with 1 required secret (WORKOS_API_KEY) in ConfigView when setup is complete.

What this data is. WorkOS is the sign-in layer a software company builds into its own product. The organizations, SSO connections and directories in WorkOS belong to that company’s customers, and the AuthKit users are the people who use the product. ConfigView reads that customer-facing access estate: organizations and their domains, SSO connections (type and state), Directory Sync directories and the users and groups synced from them, AuthKit users with their organization memberships and roles, invitations, the roles defined in the environment, the audit log actions you defined, and WorkOS’s event stream. It never reads sessions, passwords, MFA factors, directory raw attributes, user metadata, Vault data, or the audit log events themselves. ConfigView never creates, changes or deletes anything in WorkOS.

What you need

A WorkOS dashboard account with access to API Keys for the environment you want to read
Know which environment that is. A WorkOS API key reads one environment (production or staging). To read both, add a second WorkOS connection in ConfigView with the other environment’s key

Your own WorkOS dashboard team members are not collected. WorkOS does not offer an API for listing the people who can sign in to the WorkOS dashboard (its Platform API returns only a team’s name and production state). Review dashboard members under Settings in WorkOS.

Step 1: Open the WorkOS page in ConfigView

Open ConfigView in a second browser tab and leave it open: https://{companyname}.configview.com/admin/integrations/workos WorkOS shows a production API key only once, when it is created, so paste it straight into ConfigView instead of keeping it in a notes file.

Step 2: Copy an API key

Sign in to the WorkOS dashboard and switch to the environment you want to read
Open API Keys
Create a key named ConfigView (or copy the environment’s existing key). It starts with sk_
Switch to the ConfigView tab and paste it into WORKOS_API_KEY under Credentials, then click the save icon

Use a key meant only for ConfigView so you can rotate or revoke it without touching your product.

Step 3: Connect and verify

Back on https://{companyname}.configview.com/admin/integrations/workos, confirm the credential shows as saved
Click Connect. ConfigView creates its tables and schedules every collector at your default run time. Stop any you don’t want under Collectors:

Script	Notes
Organizations	The organizations (your customers’ tenants), with their domains and how many are verified.
Organization Domains	Every domain an organization has claimed, and whether it is verified or still pending.
SSO Connections	Every SAML or OIDC connection: organization, identity provider type, name and state.
Directories	Every Directory Sync directory: organization, provider type and state.
Directory Users	People synced from those directories: email, name, job title, state and role. Reads one directory at a time.
Directory Groups	Groups synced from those directories.
AuthKit Users	The end users of your product: email, verification, last sign-in.
Organization Memberships	Which user belongs to which organization, with their roles and status. Makes one request per organization.
Invitations	AuthKit invitations and whether each is pending, accepted, expired or revoked.
Roles	The roles defined in this environment and their permissions.
Audit Log Actions	The audit log actions you defined, with their schemas.
Events	WorkOS’s event stream. ConfigView keeps every event it collects.

Click Verify now. The health check reads the key, lists one organization, and tries one record from each of the other areas.

If a check fails:

The API call fails with 401. The key is wrong, was revoked, or belongs to another environment. Copy the key again.
The API call fails with 403. The key lacks permission to read organizations.
An area shows as skipped. WorkOS answered “forbidden” or “not found” for it, which usually means the feature (Directory Sync, AuthKit, Audit Logs) is not enabled in this environment. Nothing to fix.

Data Tables

Once the scripts run, these tables are created in your database. Each table has a run_at column and a raw_json column, which holds the record as WorkOS returned it, minus anything listed under What isn’t collected. The snapshot tables keep only the newest run. workos_events keeps every event ever collected.

Table	Source	Key Columns
`workos_organizations`	`GET /organizations`	organization_id, name, external_id, domains, domain_count, verified_domain_count, created_at
`workos_organization_domains`	`GET /organizations` (each organization’s domains)	domain_id, organization_id, domain, domain_state, verification_strategy
`workos_connections`	`GET /connections`	connection_id, organization_id, name, connection_type, connection_state, domains
`workos_directories`	`GET /directories`	directory_id, organization_id, name, directory_type, directory_state, domain, metadata_json
`workos_directory_users`	`GET /directory_users` (once per directory)	directory_user_id, directory_id, organization_id, email, first_name, last_name, job_title, user_state, role_slug
`workos_directory_groups`	`GET /directory_groups` (once per directory)	group_id, directory_id, organization_id, name
`workos_users`	`GET /user_management/users`	user_id, email, first_name, last_name, email_verified, external_id, last_sign_in_at
`workos_organization_memberships`	`GET /user_management/organization_memberships` (once per organization)	membership_id, user_id, user_email, organization_id, membership_status, role_slug, role_slugs, directory_managed
`workos_invitations`	`GET /user_management/invitations`	invitation_id, email, invitation_state, organization_id, inviter_user_id, expires_at
`workos_roles`	`GET /authorization/roles`	slug, name, role_type, permissions
`workos_audit_log_actions`	`GET /audit_logs/actions`	action_name, schema_version, target_types, metadata_fields
`workos_events`	`GET /events`	event_id, event_at, event_type, organization_id, user_id, connection_id, directory_id, subject_id

Things worth knowing

One key, one environment. Production and staging are separate in WorkOS. ConfigView shows whichever environment the key belongs to. Organizations are your customers. Their people are in workos_directory_users (synced from the customer’s directory) and workos_users (people who signed up through AuthKit). Join workos_organization_memberships to workos_organizations on organization_id to see who belongs to which customer, and to workos_users on user_id. States are WorkOS’s. Connection, directory, domain and invitation states are stored as WorkOS reports them (for example active, inactive, draft, invalid_credentials, unlinked, pending, verified). The event log is a 30-day window. WorkOS serves roughly the last 30 days of events. The first run collects those and every later run picks up from the newest event stored, so ConfigView becomes the longer record. Sign-in successes and directory user create/update/delete events are not requested because of their volume. Directory user changes are visible by comparing the workos_directory_users snapshot over time. Group membership is not collected. Reading who is in each directory group needs one request per group. Directory users and directory groups are collected separately. Rate limits. WorkOS allows 6,000 requests per 60 seconds per API key, 1,000 AuthKit reads per 10 seconds per environment, and 4 requests per second per directory for directory users. ConfigView paces itself well below all three: 300 requests a minute per script, and 150 a minute for directory reads, one directory at a time. A large environment can take several minutes to read because Organization Memberships makes one request per organization.

What isn’t collected

Your WorkOS dashboard team members (WorkOS has no API for them)
Directory users’ raw and custom attributes, AuthKit user metadata and profile pictures
Invitation tokens and accept links, and domain verification tokens
Sessions, passwords, MFA factors, Vault data and audit log event contents
Organization-specific custom roles and the API keys your customers created
The API key itself never goes into the database

​What you need

​Step 1: Open the WorkOS page in ConfigView

​Step 2: Copy an API key

​Step 3: Connect and verify

​Data Tables

​Things worth knowing

​What isn’t collected