@workos/mcp-docs-server 0.1.0

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

@@ -0,0 +1,240 @@
+---
+title: Admin Portal
+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.
+
+![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.
+
+![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.
+
+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 |
+
+---
+
+## Before getting started
+
+To get the most out of these guides, you’ll need:
+
+- A [WorkOS account](https://dashboard.workos.com/)
+
+## API object definitions
+
+[Connection](/reference/sso/connection)
+: 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.
+
+[Portal Link](/reference/admin-portal/portal-link)
+: A temporary link to initiate an Admin Portal session.
+
+## (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.
+
+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.
+
+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
+
+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)
+
+### 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.
+
+### 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.
+
+## (B) Integrate with your app
+
+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.
+
+### 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)
+
+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)
+
+> All redirect links must use HTTPS.
+
+You can configure these links in the [Dashboard](https://dashboard.workos.com/).
+
+### Install the WorkOS SDK
+
+WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.
+
+<LanguageSelector>
+  Install the SDK using the command below.
+
+  <CodeBlock title="Install the WorkOS SDK" file="install-sdk">
+    <CodeBlockTab language="js" file="install-sdk-npm" title="npm" />
+    <CodeBlockTab language="js" file="install-sdk-yarn" title="Yarn" />
+    <CodeBlockTab language="java" file="install-sdk-maven" title="Maven" />
+    <CodeBlockTab language="java" file="install-sdk-gradle" title="Gradle" />
+    <CodeBlockTab language="ruby" file="install-sdk-terminal" title="Terminal" />
+    <CodeBlockTab language="ruby" file="install-sdk-bundler" title="Bundler" />
+  </CodeBlock>
+</LanguageSelector>
+
+### Set secrets
+
+To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets, such as `WORKOS_API_KEY` and `WORKOS_CLIENT_ID`, and pass them to the SDKs either as environment variables or directly in your app's configuration based on your preferences.
+
+```plain title="Environment variables"
+WORKOS_API_KEY='sk_example_123456789'
+WORKOS_CLIENT_ID='client_123456789'
+```
+
+### 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.
+
+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.
+
+<CodeBlock title="Create an Organization" file="create-organization">
+  <CodeBlockTab language="js" file="create-organization-next" title="Next.js" />
+  <CodeBlockTab
+    language="js"
+    file="create-organization-express"
+    title="Express"
+  />
+  <CodeBlockTab
+    language="ruby"
+    file="create-organization-rails"
+    title="Rails"
+  />
+  <CodeBlockTab
+    language="ruby"
+    file="create-organization-sinatra"
+    title="Sinatra"
+  />
+  <CodeBlockTab
+    language="python"
+    file="create-organization-django"
+    title="Django"
+  />
+  <CodeBlockTab
+    language="python"
+    file="create-organization-flask"
+    title="Flask"
+  />
+</CodeBlock>
+
+### 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.
+
+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).
+
+> The endpoint that redirects a user to the Admin Portal should be guarded by auth in your application and only available to IT admins.
+
+<CodeBlock title="Redirect to Admin Portal" file="redirect-to-admin-portal">
+  <CodeBlockTab
+    language="js"
+    file="redirect-to-admin-portal-next"
+    title="Next.js"
+  />
+  <CodeBlockTab
+    language="js"
+    file="redirect-to-admin-portal-express"
+    title="Express"
+  />
+  <CodeBlockTab
+    language="ruby"
+    file="redirect-to-admin-portal-rails"
+    title="Rails"
+  />
+  <CodeBlockTab
+    language="ruby"
+    file="redirect-to-admin-portal-sinatra"
+    title="Sinatra"
+  />
+  <CodeBlockTab
+    language="python"
+    file="redirect-to-admin-portal-django"
+    title="Django"
+  />
+  <CodeBlockTab
+    language="python"
+    file="redirect-to-admin-portal-flask"
+    title="Flask"
+  />
+</CodeBlock>
+
+An [optional return_url parameter](/reference/admin-portal/portal-link/generate) can be used to describe exactly where a user should be sent when they are finished in the Admin Portal. If one is not provided, the success URL configured on the [Redirects](https://dashboard.workos.com/redirects) page of the dashboard will be used.
+
+## (C) Using Admin Portal
+
+In this guide, we’ll review the features of Admin Portal from an IT manager’s perspective.
+
+### 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.
+
+![A screenshot showing the Admin Portal SSO screen and where to click the “Test Single Sign-On” button.](https://images.workoscdn.com/images/b9ab3cc1-c524-4eae-9a25-f4c6a4059683.png?auto=format&fit=clip&q=50)
+
+You may also edit your metadata configuration from the Admin Portal.
+
+![A screenshot showing the Admin Portal SSO screen and where to "Edit Metadata Configuration".](https://images.workoscdn.com/images/2ada73aa-dfa4-45c8-afc8-2e69a3a9b4fc.png?auto=format&fit=clip&q=50)
+
+The Sessions section displays a list of recent sessions by timestamp, and can be sorted by `state`.
+
+![A screenshot showing the Admin Portal SSO screen and how to sort "Sessions" by "state".](https://images.workoscdn.com/images/0b1b05a0-8c18-4c99-8d02-22f2b4f2bf46.png?auto=format&fit=clip&q=50)
+
+Click on a session in the list to see session details, such as the request made to the IdP, and the response.
+
+![A screenshot showing the "Session Details" within the Admin Portal SSO screen.](https://images.workoscdn.com/images/6655ae75-c0c2-4b0c-be7b-b21dbfb6aadd.png?auto=format&fit=clip&q=50)
+
+If you wish to reset your SSO connection and set it up from scratch, select “Reset Connection” and follow the prompts.
+
+![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
+
+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.
+
+![A screenshot showing Admin Portal Directory Sync screen details.](https://images.workoscdn.com/images/13be17b8-46da-4c2c-801f-029be3686101.png?auto=format&fit=clip&q=50)
+
+You may also view and edit the attribute map from the synced directory by clicking "Edit Attribute Map".
+
+![A screenshot showing editing the attribute map in the Admin Portal Directory Sync screen.](https://images.workoscdn.com/images/c6dd347f-15dc-4918-9820-946f38361c2e.png?auto=format&fit=clip&q=50)
+
+If you wish to update the groups that are being synced, select "Edit groups sync” and follow the prompts on the next page.
+
+![A screenshot showing editing user groups in the Admin Portal Directory Sync screen.](https://images.workoscdn.com/images/05fc69da-3688-4c90-873b-505be64779b9.png?auto=format&fit=clip&q=50)
+
+You can also view a complete list of users from all selected groups in your synced directory.
+
+![A screenshot showing the user list in the Admin Portal Directory Sync screen.](https://images.workoscdn.com/images/f581e97e-2052-4635-805c-fad3c47f792e.png?auto=format&fit=clip&q=50)

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

@@ -0,0 +1,22 @@
+---
+title: Audit Logs
+links:
+  - title: Getting Started
+    links:
+      - title: Quick Start
+        url: /audit-logs
+  - title: Going Live
+    links:
+      - title: Exporting Events
+        url: /audit-logs/exporting-events
+      - title: Metadata Schema
+        url: /audit-logs/metadata-schema
+      - title: Editing Events
+        url: /audit-logs/editing-events
+      - title: Admin Portal
+        url: /audit-logs/admin-portal
+      - title: Log Streams
+        url: /audit-logs/log-streams
+originalPath: .tmp-workos-clone/packages/docs/content/audit-logs/_navigation.mdx
+---
+

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

@@ -0,0 +1,20 @@
+---
+title: 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
+---
+
+## Creating Admin Portal Link
+
+Audit Log events can be viewed in the WorkOS [Admin Portal](/admin-portal). Links can be generated through the WorkOS API and sent to your customers for viewing events associated with their Organization.
+
+When creating a link for an Admin Portal session, you must provide the Organization ID whose events will be displayed in the Admin Portal, and specify the intent as `audit_logs`.
+
+<CodeBlock
+  title="Create Admin Portal Link for Audit Logs"
+  file="create-admin-portal-link"
+/>
+
+Navigating to the provided link will result in the following view. Users will be able to view and export Audit Log events just as can be done through the WorkOS Dashboard.
+
+![A screenshot showing Audit Log events in the WorkOS Admin Portal.](https://images.workoscdn.com/images/e08a07dd-4539-4c5a-9802-63d7c774b2c9.png?auto=format&fit=clip&q=50)

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

@@ -0,0 +1,27 @@
+---
+title: Editing Events
+description: "Modify existing event configuration with\_backwards compatibility."
+originalPath: .tmp-workos-clone/packages/docs/content/audit-logs/editing-events.mdx
+---
+
+## Editing Events
+
+Once you’ve successfully configured Audit Logs in the WorkOS Dashboard and begun emitting events, how do you go about modifying an event schema without breaking your existing integrations? This is where versioning comes into place. When you make a modification to an existing schema it will create a new version rather than overwriting the existing schema.
+
+The reason for this behavior is to ensure backwards compatibility. Schema configuration is immutable to prevent you from accidentally making changes that are incompatible with events that are already being emitted from your application. Rather you must first create a new version of the schema, and then explicitly emit events for that version leveraging the event `version` field.
+
+### Creating a new event version
+
+In the WorkOS Dashboard navigate to the Audit Logs configuration page. Locate the event that you would like to modify the schema for and click the “Edit Event” item under the context menu.
+
+![A screenshot showing the "Edit Event" option in the WorkOS Dashboard.](https://images.workoscdn.com/images/8ee56828-fc59-4c18-ae64-008a754cd2a6.png?auto=format&fit=clip&q=50)
+
+You will be navigated to a page where you can edit both the `targets` associated with the event, and optionally the metadata JSON schema. Once you’re done making changes, clicking save will create a new version of the event schema.
+
+![A screenshot showing the "Save as new version" button in the schema editor in the WorkOS Dashboard.](https://images.workoscdn.com/images/65d234a3-f530-4051-95a0-0162cfef122e.png?auto=format&fit=clip&q=50)
+
+### Emitting event with version
+
+Now that a schema exists with a new version, the `version` field must be provided when emitting an event so that WorkOS knows which version to use for validation.
+
+<CodeBlock title="Emit event" file="emit-event-with-version" />

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

@@ -0,0 +1,29 @@
+---
+title: Exporting Events
+description: "Export Audit Log Events through the\_WorkOS Dashboard and API."
+originalPath: .tmp-workos-clone/packages/docs/content/audit-logs/exporting-events.mdx
+---
+
+## Exporting Events
+
+You may need to export Audit Log Events in large chunks. WorkOS supports exporting events as CSV files through both the Dashboard and API.
+
+Exports are scoped to a single organization within a specified date range. Events from the past three months can be included in the export. You may define additional filters such as `actions`, `actors`, and `targets`.
+
+### Creating an export through the Dashboard
+
+Exports can be manually created under the Organization page when viewing Audit Log Events by selecting "Export CSV" from the "Actions" dropdown. Set your filters and select "Generate CSV file".
+
+![A screenshot showing how to generate an Audit Log export in the WorkOS Dashboard.](https://images.workoscdn.com/images/a5386939-652f-4cbb-aa88-7159e2ffc1dd.png?auto=format&fit=clip&q=50)
+
+### Creating an export through the API
+
+<CodeBlock title="Create an Export" file="create-export" />
+
+Once the export has been created, fetch the export at a later time to access the `url` of the generated CSV file.
+
+> The URL will expire after 10 minutes. If the export is needed again at a later time, refetching the export will regenerate the URL.
+
+<CodeBlock title="Fetch Export" file="get-export" />
+
+If the `state` of the export is still `pending`, poll the export until it is ready for download.

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

@@ -0,0 +1,110 @@
+---
+title: Audit Logs
+description: Ingest and export Audit Log Events from your application.
+originalPath: .tmp-workos-clone/packages/docs/content/audit-logs/index.mdx
+---
+
+## Introduction
+
+Audit Logs are a collection of events that contain information relevant to notable actions taken by users in your application. Every event in the collection contains details regarding what kind of action was taken (`action`), who performed the action (`actor`), what resources were affected by the action (`targets`), and additional details of when and where the action took place.
+
+```json
+{
+  "action": "user.signed_in",
+  "occurred_at": "2022-08-29T19:47:52.336Z",
+  "actor": {
+    "type": "user",
+    "id": "user_01GBNJC3MX9ZZJW1FSTF4C5938"
+  },
+  "targets": [
+    {
+      "type": "team",
+      "id": "team_01GBNJD4MKHVKJGEWK42JNMBGS"
+    }
+  ],
+  "context": {
+    "location": "123.123.123.123",
+    "user_agent": "Chrome/104.0.0.0"
+  }
+}
+```
+
+These events are similar to application logs and analytic events, but are fundamentally different in their intent. They aren’t typically used for active monitoring/alerting, rather they exist as a paper trail of potentially sensitive actions taken by members of an organization for compliance and security reasons.
+
+## What you’ll build
+
+This guide will show you how to:
+
+1. Configure and emit Audit Log Events
+2. Export Audit Log Events
+3. Create custom metadata schemas for Audit Log Events
+4. Create new versions of Audit Log Event schemas
+
+## Before getting started
+
+To get the most out of this guide, you’ll need:
+
+- A [WorkOS account](https://dashboard.workos.com/)
+
+## API object definitions
+
+[Audit Log Event](/reference/audit-logs/create-event)
+: An individual event that represents an action taken by an actor within your app.
+
+[Audit Log Export](/reference/audit-logs/audit-log-export)
+: A collection of Audit Log Events that are exported from WorkOS as a CSV file.
+
+[Organization](/reference/organization)
+: Describes a customer where Audit Log Events originate from.
+
+## Emit an Audit Log Event
+
+### Install the WorkOS SDK
+
+WorkOS offers native SDKs in several popular programming languages. Choose a language below to see instructions in your application’s language.
+
+<LanguageSelector>
+  Install the SDK using the command below.
+
+  <CodeBlock title="Install the WorkOS SDK" file="install-sdk">
+    <CodeBlockTab language="js" file="install-sdk-npm" title="npm" />
+    <CodeBlockTab language="js" file="install-sdk-yarn" title="Yarn" />
+    <CodeBlockTab language="java" file="install-sdk-maven" title="Maven" />
+    <CodeBlockTab language="java" file="install-sdk-gradle" title="Gradle" />
+    <CodeBlockTab language="ruby" file="install-sdk-terminal" title="Terminal" />
+    <CodeBlockTab language="ruby" file="install-sdk-bundler" title="Bundler" />
+  </CodeBlock>
+</LanguageSelector>
+
+### Set secrets
+
+To make calls to WorkOS, provide the API key and, in some cases, the client ID. Store these values as managed secrets, such as `WORKOS_API_KEY` and `WORKOS_CLIENT_ID`, and pass them to the SDKs either as environment variables or directly in your app's configuration based on your preferences.
+
+```plain title="Environment variables"
+WORKOS_API_KEY='sk_example_123456789'
+WORKOS_CLIENT_ID='client_123456789'
+```
+
+### Sign in to your WorkOS Dashboard account and configure Audit Log Event schemas
+
+Before you can emit any Audit Log Events you must configure the allowed event schemas. To start, click “Create an event” and enter `user.signed_in` for action, `team` for targets, and click “Save event”.
+
+![A screenshot showing how to create an audit log event in the WorkOS dashboard.](https://images.workoscdn.com/images/7658a3b2-1467-4c38-a98f-f99f933c5969.png?auto=format&fit=clip&q=50)
+
+### Get an Organization ID
+
+All events are scoped to an Organization, so you will need the ID of an Organization in order to emit events.
+
+![A screenshot showing where to find an Organization ID in the WorkOS dashboard.](https://images.workoscdn.com/images/b76c7593-1d85-4f28-951e-24f177b8c233.png?auto=format&fit=clip&q=50)
+
+### Emit Events
+
+Using the ID from the Organization, emit an Audit Log Event with the `action` and `targets` previously configured.
+
+<CodeBlock title="Emit event" file="emit-event" />
+
+### 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.
+
+![A screenshot showing Audit Log events for an organization in the WorkOS dashboard.](https://images.workoscdn.com/images/b03dfaa4-c76a-4d08-a322-53458ba8b24d.png?auto=format&fit=clip&q=50)

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

@@ -0,0 +1,56 @@
+---
+title: Log Streams
+description: Stream Audit Log Events to your customers’ SIEM providers.
+originalPath: .tmp-workos-clone/packages/docs/content/audit-logs/log-streams.mdx
+---
+
+## Understanding Log Streams
+
+Log Streams allow your customers to stream Audit Logs directly to their Security Incident and Event Management (SIEM) providers like Datadog or Splunk and object storage solutions like AWS S3 or Google Cloud Storage. There is also a generic provider (HTTP POST) available to stream logs to any configured endpoint.
+
+This gives your customers greater control over their Audit Logs by allowing them to apply custom indexing and monitoring of their events in the SIEM provider along with events from other cloud services they use.
+
+Log Streams can be created by either configuring the Log Stream through your WorkOS Dashboard or by allowing your customer's IT admin to configure it themselves through the WorkOS Admin Portal.
+
+### IP allowlist
+
+WorkOS streams audit logs from a fixed set of IP addresses. If audit logs are being streamed to a host that restricts access based on IP address, the following IP addresses should be allowed:
+
+```plain title="WorkOS IP addresses"
+3.217.146.166
+23.21.184.92
+34.204.154.149
+44.213.245.178
+44.215.236.82
+50.16.203.9
+52.1.251.34
+52.21.49.187
+174.129.36.47
+```
+
+## Dashboard
+
+To configure a Log Stream through the WorkOS Dashboard, navigate to an organization and click “Configure”.
+
+![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.
+
+![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)
+
+## Admin Portal
+
+The Admin Portal can be accessed via a Setup Link found in the Organization page within the Dashboard. Click “Generate” and select “Log Streams”. Copy the link and send it to the organization's IT admin who will be configuring Log Streams.
+
+![A screenshot showing where the "Generate" button is located in the WorkOS Dashboard.](https://images.workoscdn.com/images/f6410460-40e4-478c-b663-5920ac15b8a8.png?auto=format&fit=clip&q=50)
+
+You can also guide users to the Admin Portal by redirecting them to a programmatically generated Admin Portal link directly from your application.
+
+<CodeBlock
+  title="Create Admin Portal Link for Log Streams"
+  file="create-log-stream-admin-portal-link"
+/>
+
+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)

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

@@ -0,0 +1,21 @@
+---
+title: Metadata Schema
+description: "Define strict JSON Schema for\_validating event metadata."
+originalPath: .tmp-workos-clone/packages/docs/content/audit-logs/metadata-schema.mdx
+---
+
+## Metadata Schema
+
+Audit Log Events can contain arbitrary metadata for adding additional details to your events. Normally this data can take any shape. However, custom metadata schemas can be defined when configuring the event for additional type safety and data consistency. When an event is emitted that does not match the provided schema, an error will be returned.
+
+When first creating an event schema, check the “Require metadata schema validation” checkbox. You will then be navigated to the schema editor where you can modify the underlying [JSON Schema](https://json-schema.org/) for all `metadata` objects.
+
+![A screenshot showing how to require metadata schema validation in the WorkOS Dashboard.](https://images.workoscdn.com/images/24a410e1-72aa-4f5b-8854-98a4307602ff.png?auto=format&fit=clip&q=50)
+
+There are `metadata` objects located at the root of the event, and within `actor` and `targets` objects. Each can contain a unique JSON Schema. To add to a `metadata` object, click the "+" sign.
+
+> Metadata objects have a limit of 50 keys. Key names can be up to 40 characters long, and values can be up to 500 characters long.
+
+![A screenshot showing the schema editor in the WorkOS Dashboard.](https://images.workoscdn.com/images/7d9e37a3-2e8d-4910-b85d-34c224e375be.png?auto=format&fit=clip&q=50)
+
+<CodeBlock title="Event with metadata" file="emit-event-with-metadata" />

package/.docs/organized/docs/custom-domains/_navigation.mdx

@@ -0,0 +1,16 @@
+---
+title: Custom Domains
+links:
+  - title: Overview
+    url: /custom-domains
+  - title: Email Domain
+    url: /custom-domains/email
+  - title: AuthKit Domain
+    url: /custom-domains/authkit
+  - title: Admin Portal Domain
+    url: /custom-domains/admin-portal
+  - title: Authentication API Domain
+    url: /custom-domains/auth-api
+originalPath: .tmp-workos-clone/packages/docs/content/custom-domains/_navigation.mdx
+---
+

package/.docs/organized/docs/custom-domains/admin-portal.mdx

@@ -0,0 +1,38 @@
+---
+title: Admin Portal Domain
+description: Guidance on configuring a custom domains for the Admin Portal.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/custom-domains/admin-portal.mdx
+---
+
+## Configuring a domain
+
+When your customer's organization admins use the Admin Portal self-serve onboarding experience, they'll be directed to a `setup.workos.com` domain.
+
+While developing with WorkOS in a staging environment, users will see the `setup.workos.com` domain.
+
+In production environments, users will see `setup.workos.com` by default or a custom domain if configured.
+
+> You must configure an [Authentication API domain](/custom-domains/auth-api) first in order for your custom Admin Portal domain to work properly.
+
+### (1) Navigate to Domains configuration
+
+With the production environment selected, navigate to the _Domains_ section of the [WorkOS Dashboard](https://dashboard.workos.com/).
+
+![Dashboard displaying domain configuration settings](https://images.workoscdn.com/images/b6afe130-219c-4e0e-8209-49b1a0fb6098.png?auto=format&fit=clip&q=80)
+
+### (2) Add an Admin Portal domain
+
+Click the _Configure Admin Portal domain_ button and enter the domain you would like to use.
+
+![Dashboard displaying a domain entry input](https://images.workoscdn.com/images/6dc8c261-3f1a-4d7a-b9ea-e7541d5e1361.png?auto=format&fit=clip&q=80)
+
+### (3) Create CNAME records
+
+You will be prompted to add a CNAME record to your DNS provider. If your DNS provider is Cloudflare, ensure the CNAME record is configured as DNS-only and is not proxied. To manage custom domains, WorkOS uses Cloudflare, who prohibit domains from being proxied across accounts.
+
+![Dashboard displaying CNAME entries](https://images.workoscdn.com/images/467edbdc-ba6d-42be-809e-7b0b1e560385.png?auto=format&fit=clip&q=80)
+
+> It can take some time for DNS changes to take effect. If the initial verification attempt is not successful, WorkOS will continue trying to verify your domain for 72 hours.
+
+Once your domain is successfully verified, admins using the self-serve Admin Portal will be redirected to your custom domain.

package/.docs/organized/docs/custom-domains/auth-api.mdx

@@ -0,0 +1,59 @@
+---
+title: Authentication API Domain
+description: Guidance on configuring a custom domain for the Authentication API.
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/custom-domains/auth-api.mdx
+---
+
+## Configuring a domain
+
+WorkOS authentication requests are done via the Authentication API, which defaults to `api.workos.com`. This can be configured to a custom domain if you prefer to use your own branding instead of the default.
+
+While developing with WorkOS in a Sandbox environment, requests are made to the `api.workos.com` domain. In production environments, requests are made to `api.workos.com` by default or a custom domain if configured.
+
+For instance, if you were retrieving a user via the API and you had a custom Authentication API domain `api.example.com` set up, you'd make requests to:
+
+`https://api.example.com/user_management/users/:id`
+
+Instead of the default:
+
+`https://api.workos.com/user_management/users/:id`
+
+> When a custom domain is configured, requests to the API should be routed through that domain. Continuing to make requests to `api.workos.com` after a custom domain is configured for the Authentication API can result in issues with your integration.
+
+### Custom domains for SCIM endpoints
+
+Custom Authentication API domains are also used for SCIM endpoints when using [Directory Sync](/directory-sync). For example, if you had a custom domain `api.example.com` set up, your customer's identity provider would make requests to `https://api.example.com/scim/v2.0/:id`. The custom domain is reflected in the Admin Portal setup steps for a directory.
+
+Adding a custom domain does not affect existing directory integrations pointing to `api.workos.com`.
+
+### Using custom domains in SDKs
+
+When using the WorkOS SDKs, a custom API hostname can be configured:
+
+<CodeBlock
+  title="Initialize a WorkOS SDK with custom hostnames"
+  file="custom-hostname"
+/>
+
+### (1) Navigate to Domains configuration
+
+With the production environment selected, navigate to the _Domains_ section of the [WorkOS Dashboard](https://dashboard.workos.com/).
+
+![Dashboard displaying domain configuration settings](https://images.workoscdn.com/images/28d1072b-1bc7-42af-8d7d-fb8da0363413.png?auto=format&fit=clip&q=80)
+
+### (2) Add an email domain
+
+Click the _Configure authentication API domain_ button and enter the domain you would like to use.
+
+![Dashboard displaying a domain entry input](https://images.workoscdn.com/images/cc648df5-603a-4001-bfc0-cea2bfca02e5.png?auto=format&fit=clip&q=80)
+
+### (3) Create CNAME records
+
+You will be prompted to add a CNAME record to your DNS provider. If your DNS provider is Cloudflare, ensure the CNAME record is configured as DNS-only and is not proxied. To manage custom domains, WorkOS uses Cloudflare, who prohibit domains from being proxied across accounts.
+
+![Dashboard displaying CNAME entries](https://images.workoscdn.com/images/e920f0c9-4bd5-4f11-a2e3-9d709b483ed1.png?auto=format&fit=clip&q=80)
+
+> It can take some time for DNS changes to take effect. If the initial verification attempt is not successful, WorkOS will continue trying to verify your domain for 72 hours.
+
+Once your domain is successfully verified, your custom domain will act as the [ACS URL](/glossary/acs-url) for authentication.