@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/admin-portal/index.mdx

@@ -1,30 +1,32 @@
 ---
 title: Admin Portal
-description: "A first-class Single\_Sign-On and\_Directory\_Sync onboarding experience\_for\_organization admins."
+description: >-
+  A first-class Single Sign-On and Directory Sync onboarding experience for
+  organization admins.
 showNextPage: true
 originalPath: .tmp-workos-clone/packages/docs/content/admin-portal/index.mdx
 ---
 
 ## Introduction
 
-The Admin Portal provides an out-of-the-box UI for IT admins to configure SSO and Directory Sync Connections. Designed to remove friction, custom walk-through documentation for each Identity Provider means that organization admins can onboard their organizations without high-touch support from your team. Easy to integrate and fully maintained and hosted by WorkOS, the Admin Portal makes the SSO and Directory Sync setup process simple, fast, and secure.
+The Admin Portal provides an out-of-the-box UI for IT admins to verify domains, configure SSO and Directory Sync connections, and more. Designed to remove friction, custom walk-through documentation for each identity provider means that organization admins can onboard their organizations without high-touch support from your team. Easy to integrate and fully maintained and hosted by WorkOS, the Admin Portal makes Domain Verification, SSO, and Directory Sync setup simple, fast, and secure.
 
 ![A screenshot showing the IdP selection in the WorkOS Admin Portal.](https://images.workoscdn.com/images/dd00d92d-2810-484a-a3c7-4e0fdb8703a7.png?auto=format&fit=clip&q=50)
 
 ## Workflow Options
 
-There are two main workflows for initiating an Admin Portal session for IT admins. You can either share a link to the Admin Portal from the WorkOS Dashboard, or you can seamlessly integrate Admin Portal into your application through WorkOS SDKs or APIs.
+There are two main workflows for initiating an Admin Portal session for IT admins. You can either share a link to the Admin Portal from the WorkOS dashboard, or you can seamlessly integrate Admin Portal into your application through WorkOS SDKs or APIs.
 
 ![A screenshot showing the different workflows for creating an Admin Portal shareable link.](https://images.workoscdn.com/images/33851982-5baf-4ffe-8b41-71054b95948b.png?auto=format&fit=clip&q=50)
 
-If you want to provide an IT admin with a link to the Admin Portal, in a email for example, then you would need to create that link in the WorkOS Dashboard.
+If you want to provide an IT admin with a link to the Admin Portal, in a email for example, then you would need to create that link in the WorkOS dashboard.
 
 However, if you are adding a button to open the Admin Portal from within your application, then you would need to use the API.
 
 | Workflow                        | Use cases                    | Security                                                                         | Return URL and Success URLs                                                                                                                |
 | ------------------------------- | :--------------------------- | :------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
 | Share a link from the dashboard | Setup only                   | Can be revoked; Automatically revoked on setup completion; Expires after 30 days | Not applicable                                                                                                                             |
-| Generate a link via the API     | Setup and post-configuration | Can not be revoked; Expires after 5 minutes                                      | Can be configured on the [Redirects](https://dashboard.workos.com/redirects) page in the dashboard or specified as a parameter for the API |
+| Generate a link via the API     | Setup and post-configuration | Cannot be revoked; Expires after 5 minutes                                       | Can be configured on the [Redirects](https://dashboard.workos.com/redirects) page in the dashboard or specified as a parameter for the API |
 
 ---
 
@@ -40,30 +42,30 @@ To get the most out of these guides, you’ll need:
 : Represents the method by which users of an organization sign in to your application.
 
 [Organization](/reference/organization)
-: Describes an organization whose users sign in with a SSO Connection, or whose users are synced with a Directory Sync Connection.
+: Describes an organization whose users sign in with an SSO connection, or whose users are synced with a Directory Sync connection.
 
-[Portal Link](/reference/admin-portal/portal-link)
+[Portal link](/reference/admin-portal/portal-link)
 : A temporary link to initiate an Admin Portal session.
 
-## (A) Setup Link from WorkOS Dashboard
+## (A) Setup link from WorkOS dashboard
 
-The Admin Portal Setup Link gives your customer access to a guided configuration experience through our Admin Portal. It instructs them how to configure their Identity or Directory Provider. If successfully configured, no other action is required and you’ll see an Active connection appear under the Organization.
+The Admin Portal setup link gives your customer access to a guided configuration experience through our Admin Portal. It instructs them how to verify a domain, configure their identity or directory provider, and more. If successfully configured, no other action is required and you’ll see verified domains and/or active connections appear under the organization.
 
-First decide whether your customer will be configuring an Identity Provider, a Directory Provider OR both. Once you generate a link, the customer will have access for 30 days or until configured.
+First decide whether your customer will be configuring Domain Verification, Single Sign-On, Directory Sync, Log Streams, or all of the above. Once you generate a link, the customer will have access for 30 days or until configured.
 
-You’ll need a [WorkOS Dashboard account](https://dashboard.workos.com/) to create an organization that will represent the enterprise you are onboarding.
+You’ll need a [WorkOS dashboard account](https://dashboard.workos.com/) to create an organization that will represent the enterprise you are onboarding.
 
-### Create Organization
+### Create organization
 
-Sign in to your WorkOS Dashboard account and create a new Organization.
+Sign in to your WorkOS dashboard account and create a new organization.
 
-![WorkOS Dashboard UI showing organization creation](https://images.workoscdn.com/images/1c69fd98-01be-491d-9255-58363bc6a983.png?auto=format&fit=clip&q=50)
+![WorkOS dashboard UI showing organization creation](https://images.workoscdn.com/images/1c69fd98-01be-491d-9255-58363bc6a983.png?auto=format&fit=clip&q=50)
 
-### Generate a Setup Link
+### Generate a setup link
 
-Click the “Invite Admin” button, select the features to include and then click “Next." Enter the email of the IT admin for the organization to automatically send them a setup link, or click "Copy setup link." Only one link can be active at a time. After creating the initial link, you can click the “Manage” button to revoke the existing link before creating a new one.
+Click the “Invite admin” button, select the features to include and then click “Next." Enter the email of the IT admin for the organization to automatically send them a setup link, or click "Copy setup link." Only one link can be active at a time. After creating the initial link, you can click the “Manage” button to revoke the existing link before creating a new one.
 
-### Sharing a Setup Link
+### Sharing a setup link
 
 If you chose to copy the setup link you can share it over email, Slack or direct message. We also recommend including details on what the link does and how long the link is active.
 
@@ -71,21 +73,21 @@ If you chose to copy the setup link you can share it over email, Slack or direct
 
 In this guide, we’ll walk you through the full end-to-end integration of the Admin Portal into your application.
 
-> [Sign in](https://dashboard.workos.com/) to your WorkOS Dashboard account to see code examples pre-filled with your test API keys and resource IDs.
+> [Sign in](https://dashboard.workos.com/) to your WorkOS dashboard account to see code examples pre-filled with your test API keys and resource IDs.
 
 ### Configure Admin Portal redirect links
 
 In order to integrate, you must configure your app's default return URI in the production environment. A button in the Admin Portal will use this value to allow users to return to your app unless otherwise specified when generating the Admin Portal link.
 
-![A screenshot showing the Admin Portal Redirect Links tab to set redirect URIs in the WorkOS Dashboard.](https://images.workoscdn.com/images/c0b796f4-7803-413c-8633-3e99f451ad0d.png?auto=format&fit=clip&q=50)
+![A screenshot showing the Admin Portal Redirect Links tab to set redirect URIs in the WorkOS dashboard.](https://images.workoscdn.com/images/9df0f214-0350-466c-b54b-8a1e0be6b678.png?auto=format&fit=clip&q=50)
 
 Additionally, you can configure success URIs to redirect users upon successfully setting up Single Sign-On, Directory Sync, or Log Streams.
 
-![A screenshot showing the Admin Portal redirect URI variations in the WorkOS Dashboard.](https://images.workoscdn.com/images/249bb56d-9d18-46f4-aa80-a8cbea384fce.png?auto=format&fit=clip&q=50)
+![A screenshot showing the Admin Portal redirect URI variations in the WorkOS dashboard.](https://images.workoscdn.com/images/3d75975c-b36a-4bfc-b05d-d745b8ba916b.png?auto=format&fit=clip&q=50)
 
 > All redirect links must use HTTPS.
 
-You can configure these links in the [Dashboard](https://dashboard.workos.com/).
+You can configure these links in the [dashboard](https://dashboard.workos.com/).
 
 ### Install the WorkOS SDK
 
@@ -113,15 +115,15 @@ WORKOS_API_KEY='sk_example_123456789'
 WORKOS_CLIENT_ID='client_123456789'
 ```
 
-### Create a new Organization
+### Create a new organization
 
-Each Admin Portal session is scoped to a specific Organization resource, meaning a session is only capable of managing a Connection that belongs to its associated Organization. Organizations may only have one Connection.
+Each Admin Portal session is scoped to a specific organization resource, meaning a session is only capable of managing a connection that belongs to its associated organization. Organizations may only have one connection.
 
-For every customer in your application that would like access to the Admin Portal, you must create an Organization and maintain a reference to its ID.
+For every customer in your application that would like access to the Admin Portal, you must create an organization and maintain a reference to its ID.
 
-> Create an Organization when onboarding a new customer.
+> Create an organization when onboarding a new customer.
 
-<CodeBlock title="Create an Organization" file="create-organization">
+<CodeBlock title="Create an organization" file="create-organization">
   <CodeBlockTab language="js" file="create-organization-next" title="Next.js" />
   <CodeBlockTab
     language="js"
@@ -152,11 +154,9 @@ For every customer in your application that would like access to the Admin Porta
 
 ### Redirect an IT admin to the Admin Portal
 
-A Portal Link is your enterprise user’s gateway to accessing their Admin Portal. Each Portal Link is generated using an Organization resource ID. Only resources belonging to the specified Organization can be managed during a Portal Session.
+A Portal link is your enterprise user's gateway to accessing the Admin Portal, where they can set up and manage resources scoped to their organization. To generate a Portal link using the API, you must provide the organization ID and specify one of the following intents: [`sso`](/admin-portal/c-using-admin-portal/managing-sso-connections), [`dsync`](/admin-portal/c-using-admin-portal/managing-directories), [`audit_logs`](/audit-logs/admin-portal/creating-admin-portal-link), [`log_streams`](/audit-logs/log-streams/admin-portal), [`domain_verification`](/domain-verification/admin-portal-domain-verification), or [`certificate_renewal`](/sso/signing-certificates/saml-response-signing-certificate/renewing-certificates).
 
-In the API call to generate an Admin Portal Link, you will pass an `intent` with possible values of `sso` for an Admin Portal session to create an SSO connection, and `dsync` for an Admin Portal session to create a Directory Sync connection.
-
-For security reasons, Portal Links expire 5 minutes after they’re created, so we recommend redirecting users immediately (i.e. don’t email the user Portal Links).
+For security reasons, Portal links expire 5 minutes after they’re created, so we recommend redirecting users immediately (i.e. don’t email the user Portal links).
 
 > The endpoint that redirects a user to the Admin Portal should be guarded by auth in your application and only available to IT admins.
 
@@ -197,9 +197,15 @@ An [optional return_url parameter](/reference/admin-portal/portal-link/generate)
 
 ## (C) Using Admin Portal
 
-In this guide, we’ll review the features of Admin Portal from an IT manager’s perspective.
+In this guide, we’ll review some of the features of Admin Portal from an IT admin's perspective.
+
+### Verifying a domain
+
+In the Admin Portal [Domain Verification](/domain-verification/admin-portal-domain-verification) flow, you can view instructions on adding a DNS TXT record to prove ownership of your organization's domain(s).
+
+> Unless an organization [allows any domain](/sso/domains/allowing-any-domain), a verified domain is required in order to activate SSO. Domains can also be [manually verified](/authkit/domain-verification/self-serve-domain-verification) outside of the self-serve Admin Portal flow if the IT admin has already proven domain ownership in another context.
 
-### Managing SSO Connections
+### Managing SSO connections
 
 On the Admin Portal SSO screen, you can view the identity provider details and connection status, metadata configuration details, and a list of recent connection sessions. You may test your SSO connection from the Admin Portal by using the “Test sign-in” button.
 
@@ -221,7 +227,7 @@ If you wish to reset your SSO connection and set it up from scratch, select “R
 
 ![A screenshot showing how to "Reset Connection" within the Admin Portal SSO screen.](https://images.workoscdn.com/images/b0f2919d-07f2-457d-8499-1b617235c485.png?auto=format&fit=clip&q=50)
 
-### Managing Directories
+### Managing directories
 
 On the Admin Portal Directory Sync screen, you can view the directory provider details and connection status, user and group counts, and last sync time. There is also an option to reset the directory.
 

package/.docs/organized/docs/audit-logs/admin-portal.mdx

@@ -1,6 +1,6 @@
 ---
 title: Admin Portal
-description: "View Audit Log events for an\_organization in the WorkOS Admin\_Portal."
+description: View Audit Log events for an organization in the WorkOS Admin Portal.
 originalPath: .tmp-workos-clone/packages/docs/content/audit-logs/admin-portal.mdx
 ---
 

package/.docs/organized/docs/audit-logs/editing-events.mdx

@@ -1,6 +1,6 @@
 ---
 title: Editing Events
-description: "Modify existing event configuration with\_backwards compatibility."
+description: Modify existing event configuration with backwards compatibility.
 originalPath: .tmp-workos-clone/packages/docs/content/audit-logs/editing-events.mdx
 ---
 

package/.docs/organized/docs/audit-logs/exporting-events.mdx

@@ -1,6 +1,6 @@
 ---
 title: Exporting Events
-description: "Export Audit Log Events through the\_WorkOS Dashboard and API."
+description: Export Audit Log Events through the WorkOS Dashboard and API.
 originalPath: .tmp-workos-clone/packages/docs/content/audit-logs/exporting-events.mdx
 ---
 

package/.docs/organized/docs/audit-logs/index.mdx

@@ -48,10 +48,10 @@ To get the most out of this guide, you’ll need:
 
 ## API object definitions
 
-[Audit Log Event](/reference/audit-logs/create-event)
+[Audit Log Event](/reference/audit-logs/event/create)
 : An individual event that represents an action taken by an actor within your app.
 
-[Audit Log Export](/reference/audit-logs/audit-log-export)
+[Audit Log Export](/reference/audit-logs/export)
 : A collection of Audit Log Events that are exported from WorkOS as a CSV file.
 
 [Organization](/reference/organization)
@@ -103,6 +103,21 @@ Using the ID from the Organization, emit an Audit Log Event with the `action` an
 
 <CodeBlock title="Emit event" file="emit-event" />
 
+#### Idempotency
+
+WorkOS Audit Logs supports idempotency to ensure events are not duplicated when retrying requests. You can provide an `idempotency-key` header with your event creation request. If you don't provide one, WorkOS will automatically generate one based on the event content.
+
+When you provide an idempotency key:
+
+- WorkOS creates a hashed key combining your provided key with the event data
+- Subsequent requests with the same idempotency key and event data will return the same response
+- This prevents duplicate events from being created due to network retries or other issues
+
+When you don't provide an idempotency key:
+
+- WorkOS automatically generates one using the event content
+- This provides basic duplicate protection based on event data alone
+
 ### View ingested events in the Dashboard
 
 Once you have successfully emitted events with the WorkOS SDK, you can view them in the Dashboard under the Organization that the events are associated with.

package/.docs/organized/docs/audit-logs/log-streams.mdx

@@ -34,7 +34,7 @@ To configure a Log Stream through the WorkOS Dashboard, navigate to an organizat
 
 ![A screenshot showing where to find "Configure" in the WorkOS Dashboard.](https://images.workoscdn.com/images/b555ad16-fce2-4014-997d-3d75b85f7860.png?auto=format&fit=clip&q=50)
 
-You will be promoted to select a destination from a dropdown, click “Save connection”. You will then be prompted to provide specific configuration for the selected destination.
+You will be prompted to select a destination from a dropdown, click “Save connection”. You will then be prompted to provide specific configuration for the selected destination.
 
 ![A screenshot showing "Save connection" in the WorkOS Dashboard.](https://images.workoscdn.com/images/75ced694-5dbd-48c3-9784-5fdaf81e0420.png?auto=format&fit=clip&q=50)
 
@@ -54,3 +54,327 @@ You can also guide users to the Admin Portal by redirecting them to a programmat
 Once redirected to the Admin Portal, the user will be prompted to select a destination and will be provided with step-by-step configuration instructions for the selected destination.
 
 ![A screenshot showing log stream destination options in the WorkOS Admin Portal.](https://images.workoscdn.com/images/a6249873-d221-49eb-9c6a-c7706b2b4f77.png?auto=format&fit=clip&q=50)
+
+## Streaming Destinations and Payload Formats
+
+WorkOS supports streaming audit log events to six different types of destinations, each with its own payload format and configuration requirements:
+
+### Datadog
+
+Events are sent to Datadog's HTTP Log Intake API with regional endpoint support.
+
+**Example Payload:**
+
+```json
+[
+  {
+    "message": {
+      "id": "01HY123456ABCDEFGHIJK",
+      "action": "user.signed_in",
+      "targets": [
+        {
+          "id": "user_123",
+          "type": "user"
+        }
+      ],
+      "actor": {
+        "id": "user_456",
+        "type": "user"
+      },
+      "context": {
+        "location": "192.168.1.1",
+        "user_agent": "Chrome/91.0"
+      },
+      "occurred_at": "2024-01-15T10:30:00.000Z"
+    },
+    "ddsource": "team-name",
+    "service": "audit-logs"
+  }
+]
+```
+
+**Configuration:**
+
+- API Key authentication
+- Regional endpoints (US1, US3, US5, EU1, US1-FED, AP1)
+- Optional team name as source identifier
+
+### Splunk
+
+Events are sent to Splunk's HTTP Event Collector (HEC) endpoint.
+
+**Example Payload:**
+
+```json
+[
+  {
+    "event": {
+      "id": "01HY123456ABCDEFGHIJK",
+      "action": "user.signed_in",
+      "targets": [
+        {
+          "id": "user_123",
+          "type": "user"
+        }
+      ],
+      "actor": {
+        "id": "user_456",
+        "type": "user"
+      },
+      "context": {
+        "location": "192.168.1.1",
+        "user_agent": "Chrome/91.0"
+      },
+      "occurred_at": "2024-01-15T10:30:00.000Z"
+    },
+    "time": 1705314600000,
+    "source": "team-name"
+  }
+]
+```
+
+**Configuration:**
+
+- HEC Token authentication
+- Custom Splunk instance URL
+- Optional source identifier
+
+### AWS S3
+
+Events are stored as individual JSON files in an S3 bucket. We use a cross-account IAM role with an external ID
+([details](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html))
+to authenticate to the destination bucket. We upload S3 objects with a `ContentMD5` header to support
+[uploading objects to Object Lock enabled buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock-managing.html#object-lock-put-object).
+
+| Property            | Description                                                    |
+| ------------------- | -------------------------------------------------------------- |
+| File Format         | Individual JSON files per event with pretty-printed formatting |
+| File Naming Pattern | `YYYY-MM-DD/{timestamp}_{keySuffix}.json`                      |
+| Example Filename    | `2024-01-15/2024-01-15T10:30:00.123Z_abc123def456.json`        |
+
+**Example File Content:**
+
+```json
+{
+  "id": "01HY123456ABCDEFGHIJK",
+  "action": "user.signed_in",
+  "targets": [
+    {
+      "id": "user_123",
+      "type": "user"
+    }
+  ],
+  "actor": {
+    "id": "user_456",
+    "type": "user"
+  },
+  "context": {
+    "location": "192.168.1.1",
+    "user_agent": "Chrome/91.0"
+  },
+  "occurred_at": "2024-01-15T10:30:00.000Z"
+}
+```
+
+**Configuration:**
+
+WorkOS authenticates to the destination S3 bucket using an AWS cross-account IAM role delegation with an external ID for enhanced security. This requires the following configuration:
+
+| Field Name     | Code         | Description                                                              |
+| -------------- | ------------ | ------------------------------------------------------------------------ |
+| AWS Account ID | `accountId`  | Destination AWS account ID where the S3 bucket is located                |
+| AWS Region     | `region`     | The AWS region for the destination S3 bucket (defaults to `us-east-1`)   |
+| IAM Role Name  | `roleName`   | The name of the IAM role WorkOS will assume to access destination bucket |
+| S3 Bucket Name | `bucketName` | The name of the destination S3 bucket                                    |
+| Bucket Path    | `bucketPath` | Optional path prefix within the bucket where logs will be stored         |
+
+**Authentication Flow:**
+
+1. WorkOS uses AWS Security Token Service (STS) to assume a role in the destination AWS account
+2. The role must be configured to trust WorkOS' AWS account ID (`workosAccountId`) as an external trusted entity
+3. The role must require an External ID (`externalId`) that matches the unique value provided by WorkOS
+4. The role must have an attached IAM policy granting `s3:PutObject` permissions on the bucket (and optional path prefix)
+5. WorkOS receives temporary credentials from STS and uses them to upload audit log events to the destination S3 bucket
+
+**IAM Policy Requirements:**
+
+The IAM role must include a policy that allows `s3:PutObject` actions on the destination bucket. The policy resource should target destination bucket and optional path prefix: `arn:aws:s3:::bucket-name/optional-path/*`.
+
+Example policy that you need to create in the destination AWS account:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "LogStreamBucketPolicy",
+      "Effect": "Allow",
+      "Action": ["s3:PutObject"],
+      "Resource": ["arn:aws:s3:::bucket-name/optional-path/*"]
+    }
+  ]
+}
+```
+
+### Google Cloud Storage
+
+Events are stored as individual JSON files using Google Cloud Storage's S3-compatible API.
+
+| Property            | Description                                         |
+| ------------------- | --------------------------------------------------- |
+| File Format         | Individual JSON files per event (same format as S3) |
+| File Naming Pattern | `{timestamp}_{keySuffix}.json`                      |
+
+**Example File Content:**
+
+```json
+{
+  "id": "01HY123456ABCDEFGHIJK",
+  "action": "user.signed_in",
+  "targets": [
+    {
+      "id": "user_123",
+      "type": "user"
+    }
+  ],
+  "actor": {
+    "id": "user_456",
+    "type": "user"
+  },
+  "context": {
+    "location": "192.168.1.1",
+    "user_agent": "Chrome/91.0"
+  },
+  "occurred_at": "2024-01-15T10:30:00.000Z"
+}
+```
+
+**Configuration:**
+
+- Access Key ID and Secret Access Key are required when configuring a log stream to GCS
+- GCS bucket with S3-compatible access
+
+### Microsoft Sentinel
+
+Events are sent to Microsoft Sentinel via the Azure Monitor Logs Ingestion API.
+
+**Example Payload:**
+
+```json
+[
+  {
+    "TimeGenerated": "2024-01-15T10:30:00.000Z",
+    "id": "01HY123456ABCDEFGHIJK",
+    "event_type": "user.signed_in",
+    "organization_id": "org_01ABC123",
+    "data": {
+      "id": "01HY123456ABCDEFGHIJK",
+      "action": "user.signed_in",
+      "targets": [
+        {
+          "id": "user_123",
+          "type": "user"
+        }
+      ],
+      "actor": {
+        "id": "user_456",
+        "type": "user"
+      },
+      "context": {
+        "location": "192.168.1.1",
+        "user_agent": "Chrome/91.0"
+      },
+      "occurred_at": "2024-01-15T10:30:00.000Z"
+    }
+  }
+]
+```
+
+**Configuration:**
+
+| Property                     | Description                                            |
+| ---------------------------- | ------------------------------------------------------ |
+| Tenant ID                    | Azure Active Directory tenant ID                       |
+| Client ID                    | Application (client) ID from Azure AD app registration |
+| Client Secret                | Client secret from Azure AD app registration           |
+| Data Collection Endpoint URL | The URL of the Data Collection Endpoint (DCE)          |
+| Data Collection Rule ID      | The immutable ID of the Data Collection Rule (DCR)     |
+| Stream Name                  | The name of the Logs Stream                            |
+
+### Generic HTTPS
+
+Events are sent to custom HTTP endpoints with configurable authentication and format options.
+
+**JSON Format Example:**
+
+```json
+[
+  {
+    "event": {
+      "id": "01HY123456ABCDEFGHIJK",
+      "action": "user.signed_in",
+      "targets": [
+        {
+          "id": "user_123",
+          "type": "user"
+        }
+      ],
+      "actor": {
+        "id": "user_456",
+        "type": "user"
+      },
+      "context": {
+        "location": "192.168.1.1",
+        "user_agent": "Chrome/91.0"
+      },
+      "occurred_at": "2024-01-15T10:30:00.000Z"
+    },
+    "keySuffix": "abc123def456",
+    "timestamp": "2024-01-15T10:30:00.123Z",
+    "source": "team-name"
+  }
+]
+```
+
+**NDJSON Format Example:**
+
+```json
+{"event":{"id":"01HY123456ABCDEFGHIJK","action":"user.signed_in",...},"keySuffix":"abc123def456","timestamp":"2024-01-15T10:30:00.123Z"}
+```
+
+**Configuration:**
+
+- Custom HTTP endpoint
+- Configurable authentication headers
+- Support for JSON or NDJSON formats
+- Content-Type handling (application/json or application/x-ndjson)
+
+## Stream States and Management
+
+Audit log streams can be in one of four states that determine their operational status:
+
+### Stream States
+
+| State        | Description                                               |
+| ------------ | --------------------------------------------------------- |
+| **Active**   | Stream is functioning normally and delivering events      |
+| **Inactive** | Stream is incomplete, manually disabled or paused         |
+| **Error**    | Stream encountered a retry-able error and will be retried |
+| **Invalid**  | Stream has invalid credentials or configuration           |
+
+### State Transitions
+
+Streams automatically transition between states based on delivery outcomes:
+
+- **Active → Error**: When a retry-able error occurs during event delivery
+- **Active → Invalid**: When authentication or authorization fails
+- **Error → Active**: When retry succeeds after a previous error
+- **Invalid → Active**: When credentials are fixed and validation succeeds
+- **Any → Inactive**: When manually disabled through Dashboard or Admin Portal
+
+### Updating Stream Configuration
+
+Stream configurations can be updated through:
+
+1. **WorkOS Dashboard**: Navigate to the organization and modify the log stream configuration
+2. **Admin Portal**: Generate a setup link for the organization's IT admin to update settings

package/.docs/organized/docs/audit-logs/metadata-schema.mdx

@@ -1,6 +1,6 @@
 ---
 title: Metadata Schema
-description: "Define strict JSON Schema for\_validating event metadata."
+description: Define strict JSON Schema for validating event metadata.
 originalPath: .tmp-workos-clone/packages/docs/content/audit-logs/metadata-schema.mdx
 ---