Overview

WorkOS is an identity and authentication platform that provides enterprise-grade features including single sign-on, directory sync, audit logging, and multi-factor authentication for B2B SaaS applications.

Persona’s WorkOS integration helps teams centralize identity verification and investigation activity by sending structured audit events to WorkOS and by making it easy to look up the WorkOS organization identifiers required for those events. This is especially helpful for Security, Compliance, and Operations teams that need consistent audit trails across tools and customers.

Benefits

Centralized Audit Trails: Record notable Persona actions as WorkOS audit log events to support security monitoring and compliance reporting.

Reduced Manual Logging: Automatically generate audit events from workflows instead of relying on ad hoc, manual updates across teams.

Consistent Organization Context: Pull a list of WorkOS organizations so you can reliably associate events with the correct customer organization.

Integration Features

Persona’s WorkOS integration enables teams to log Persona activity into WorkOS Audit Logs and reference WorkOS organizations from within Persona workflows. Key capabilities include:

• Create Audit Log Events: Send structured audit events (action, actor, targets, context, timestamp, and optional metadata) to WorkOS.
  • List Organizations: Retrieve organizations available in your WorkOS environment to find the organization identifiers needed for audit logging.
  • Optional Metadata Support: Attach additional key-value metadata to provide richer investigation context downstream.

Setting up the WorkOS integration

Prerequisites

To set up the WorkOS integration, ensure you have:

• Admin access to your WorkOS account
• Necessary API permissions to access WorkOS credentials

Setting up the WorkOS Credentials

1. In the Persona Dashboard, navigate to Integrations > Marketplace and select WorkOS.
2. Click Add Credential.
3. Enter a credential nickname.
4. Provide your WorkOS credentials (for example, an API key from your WorkOS environment) and save the credential.
5. Click Test to confirm Persona can successfully connect to WorkOS.

Using the WorkOS integration in a workflow

1. Create a new workflow, or open an existing workflow you’d like to update.
2. Add a new action step > Integrations.
3. Select the WorkOS integration and choose your WorkOS credential.
4. Configure the input fields to pass in the correct information from your workflow.
5. Save and publish the workflow.

WorkOS Operations Overview

In addition to syncing field values, Persona can create audit log events and list organizations using WorkOS’s API. These actions support seamless two-way workflows, letting teams manage investigations without switching platforms.

See below for a comprehensive list of available Workflow Action steps and possible configurations for the WorkOS integration:

List Organizations Workflow Action Step

Retrieves the set of organizations available in your WorkOS environment, which is useful when you need to discover or confirm the organization identifier to use for downstream actions. This step is commonly used early in a workflow to ensure audit events are associated with the correct organization, especially in B2B contexts where multiple customer orgs exist.

Configuration Steps:

• Optionally add:
  • Limit: Maximum number of organizations to return per page
  • Before Cursor: Retrieve results that come before a specific cursor
  • After Cursor: Retrieve results that come after a specific cursor

Create Audit Log Event Workflow Action Step

Creates an Audit Log event in WorkOS to record a notable action performed by a user or system, and associates that event with a specific WorkOS organization. This step helps you standardize what happened, who did it, what resources were affected, and the surrounding context—so downstream teams can audit or investigate activity using WorkOS as the system of record.

Configuration Steps:

• Provide values for required fields:
  • Organization ID
  • Event
    • Action: A clear, consistent identifier describing what occurred
    • Occurred At: Timestamp for when the action occurred
    • Version: Event schema version
    • Actor
      • Actor Type
      • Actor ID
    • Targets (one or more)
      • Target Type
      • Target ID
    • Context (provide an object; you can pass an empty object if you don’t have context available)
  • Optionally add:
    • Actor Name
    • Actor Metadata
    • Target Name
    • Target Metadata
    • Context Location (for example, IP address/location)
    • Context User Agent
    • Event Metadata

FAQ

Do I need a WorkOS Organization ID to create an audit event?

Yes. WorkOS audit events must be associated with an organization, so you’ll need to provide an Organization ID when configuring the Create Audit Log Event workflow action step.

How do I find the right Organization ID?

Use the List Organizations workflow action step to retrieve organizations in your WorkOS environment, then map the appropriate organization identifier into the audit event step based on your workflow logic (for example, the customer or account you’re investigating).

What should I put in the “Action” field for an audit event?

Use a consistent naming convention that makes sense to both technical and non-technical stakeholders (for example, a concise verb phrase that describes the business action). Keeping action names consistent across workflows makes it easier to filter and review events in WorkOS over time.

Is “Context” required even if I don’t have IP address or user agent details?

Yes. WorkOS requires a context object to be provided. If you don’t have context details available, pass an empty object.