@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/directory-sync/index.mdx

@@ -0,0 +1,107 @@
+---
+title: Directory Sync
+description: "Build frictionless onboarding for\_organizations with\_real‑time user\_provisioning and deprovisioning."
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/directory-sync/index.mdx
+---
+
+## Introduction
+
+Organizations use company directories and HRIS systems to manage users and enforce their access to organization resources. Directories enable IT admins to activate and deactivate accounts, create groups that inform access rules, accelerate adoption of new tools, and more.
+
+## Definitions
+
+**ULM**
+: User Lifecycle Management (or ULM) is the process of managing a user’s access to an app. This occurs from app onboarding until they are removed from an app. ULM is also commonly referred to as identity provisioning.
+
+**SCIM**
+: System for Cross-domain Identity Management (or SCIM) is an open standard for managing automated user and group provisioning. It’s a standard that many directory providers interface with.
+
+**HRIS**
+: A Human Resources Information System (or HRIS) is software designed to maintain, manage, and process detailed employee information and human resources-related policies. Examples include: Workday, HiBob, BambooHR, etc.
+
+**User Provisioning**
+: Provisioning is the process of creating a user and setting attributes for them – inside of an app.
+
+**User Deprovisioning**
+: Deprovisioning is the process of removing a user from an app.
+
+## What is Directory Sync?
+
+Directory Sync is a set of developer-friendly APIs and IT admin tools that allows you to implement enterprise-grade User Lifecycle Management (ULM) into your existing app.
+
+ULM allows IT admins to centrally provision and deprovision users from their directory provider. A directory provider is the source of truth for your enterprise customer’s user and group lists. Directory Sync sends automatic updates to your app for changes to directories, groups, users, or access rules.
+
+Common directory providers include: [Microsoft Active Directory](/integrations/microsoft-ad-fs-saml), [Okta](/integrations/okta-scim), [Workday](/integrations/workday), and [Google Workspace](/integrations/google-directory-sync). See the full list of supported directory providers on the [integrations](/integrations) page.
+
+## Why use Directory Sync?
+
+ULM increases the security of your app and makes it easier for your customers to use your app. ULM is most often implemented using [SCIM](/glossary/scim). SCIM requests are sent between directory providers and your app to inform you of changes to a user’s identity. Changes can include:
+
+- Provisioning an identity for a user (account creation)
+- When a user’s attribute has changed (account update)
+- Deprovisioning a user from your app (account deletion)
+
+Each directory provider implements SCIM differently. Implementing SCIM is often a challenging process and can introduce security vulnerabilities into your app. Directory Sync hides this complexity, so you can focus on building core product features in your app.
+
+## What your customer experiences
+
+Let’s take a look at two different user provisioning scenarios.
+
+### (N) Your app doesn’t use Directory Sync
+
+Without ULM, your customers have to manually add, update, and remove users from your app.
+
+Imagine a scenario where your customer has purchased your software and onboards a new employee to your app. Your customer would have to do the following:
+
+1. The IT admin provisions the employee in their directory provider (_if they use one_) and manually in your app.
+2. All employee information has to be set manually in both the directory provider and your app.
+3. The IT admin has to manually provision a login method for the employee; through either SSO (_if they use an identity provider_) or a self-registration page.
+4. The IT admin sends the invite link to their employee. Often initiating a back and forth via either email, messaging app, or IT helpdesk ticket.
+5. The employee has to proceed with the registration method and can then use your app.
+
+All future changes to this employee’s data and access are manually entered by the IT admin. This is error prone and can lead to security vulnerabilities where users get unauthorized access to resources.
+
+As your customers adopt more cloud software, these manual processes do not scale well. Manual input error can lead to the source of truth (directory) drifting from your app’s state. As a result, ULM has become a table stakes product requirement for enterprises.
+
+### (Y) Your app uses Directory Sync
+
+If your app supports ULM via Directory Sync, the IT admin can provision this employee from one place:
+
+1. Add the employee to their directory provider.
+2. Assign the employee to your app with the appropriate role once; via the directory provider admin page.
+3. **Optional.** Have the employee go through a password setup if they are not using an identity provider (SSO).
+
+Directory Sync makes this integration easy by providing APIs your app interfaces with. All updates for this directory will automatically be sent to your app from WorkOS.
+
+---
+
+## API overview
+
+[Directory](/reference/directory-sync/directory), [directory group](/reference/directory-sync/directory-group), and [directory user](/reference/directory-sync/directory-user) are the main components your app interfaces with.
+
+### Directory
+
+<DirectorySyncDiagram.Directory />
+
+A directory is the source of truth for your customer’s user and group lists.
+
+WorkOS supports dozens of integrations including SCIM. Directory updates are delivered to you via webhooks. Your app stores a mapping between your customer and their directory. This allows you to maintain your app in sync with the directory provider used by your customer.
+
+You can enable self-service Directory Sync setup for your customers using the [Admin Portal](/admin-portal).
+
+### Directory group
+
+<DirectorySyncDiagram.Group />
+
+A directory group is a collection of users within an organization who have been provisioned with access to your app.
+
+Directory groups are mapped from directory provider groups. Directory groups are most often used to categorize a collection of users based on shared traits. i.e. Grouping software developers at a company under an “Engineering” group.
+
+### Directory user
+
+<DirectorySyncDiagram.User />
+
+A directory user is a person or entity within an organization who has been provisioned with access to your app.
+
+Users can belong to multiple directory groups. Users have [attributes](/directory-sync/attributes) associated with them. These attributes can be configured for your app’s needs.

package/.docs/organized/docs/directory-sync/quick-start.mdx

@@ -0,0 +1,129 @@
+---
+title: Quick Start
+description: "Set up a directory, install the SDK, and\_integrate Directory\_Sync."
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/directory-sync/quick-start.mdx
+---
+
+## What you’ll build
+
+In this guide, we’ll take you from learning about Directory Sync and POC-ing all the way through to building production-ready features fully integrated with the WorkOS Directory Sync API.
+
+This guide will show you how to:
+
+1. Create a new directory in the WorkOS Dashboard
+2. Add Directory Sync to your app and fetch directory resources
+3. Use events to keep your app in sync with the directory changes
+
+## Before getting started
+
+To get the most out of this guide, you’ll need:
+
+- A [WorkOS account](https://dashboard.workos.com/)
+- A directory from a directory provider that WorkOS supports
+
+## API object definitions
+
+[Directory](/reference/directory-sync/directory)
+: Stores info about an organization’s user management system (i.e. directory provider).
+
+[Directory user](/reference/directory-sync/directory-user)
+: Represents an organization user that is active in an organization’s directory provider.
+
+[Directory group](/reference/directory-sync/directory-group)
+: A collection of organization users within a directory, e.g. IT, database admins, HR.
+
+> The WorkOS Directory Sync API exclusively uses read-only operations. We never mutate end-user directories.
+
+---
+
+## (1) Create a new directory connection
+
+The first step to connecting with a directory is creating an organization in the [WorkOS Dashboard](https://dashboard.workos.com/). You will then be able to create a new [connection](/glossary/connection) to the organization’s directory. Let’s start by creating one for development in your sandbox environment
+
+Get provider-specific instructions by selecting the directory provider you want to test:
+
+<ProviderCards.DirSyncIntegration />
+
+> You can view and copy the unique identifier for the directory connection on the directory page, once it has been set up. The id takes the form `directory_*`.
+
+---
+
+## (2) Add Directory Sync to your app
+
+Let’s integrate the Directory Sync API into your app to enable fetching directory resources programmatically.
+
+### 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'
+```
+
+> The code examples use your staging API keys when [signed in](https://dashboard.workos.com).
+
+### Fetch directory resources
+
+Get the details of an existing directory user.
+
+Example use case: pre-populate user attributes for new user accounts.
+
+<CodeBlock title="Get directory user" file="get-directory-user" />
+
+#### List directory users
+
+Get directory users for a given directory or directory group.
+
+Example use case: Build an onboarding experience that allows an admin to select who to invite and create accounts for.
+
+<CodeBlock title="List directory users" file="list-directory-users" />
+
+> Use the optional `limit`, `before`, and `after` parameters to paginate through results. See the [API Reference](/reference/pagination) for details.
+
+#### Get directory group
+
+Get the details of an existing directory group.
+
+Example use case: Pre-populate team attributes for new organizations.
+
+<CodeBlock title="Get directory group" file="get-directory-group" />
+
+#### List directory groups
+
+Get directory groups for a given directory or directory user.
+
+Example use case: Build an onboarding experience that allows an admin to select which groups of employees to invite and create accounts for.
+
+<CodeBlock title="List directory groups" file="list-directory-groups" />
+
+> Use the optional `limit`, `before`, and `after` parameters to paginate through results. See the [API Reference](/reference/pagination) for details.
+
+---
+
+## (3) Handle directory events
+
+Actions performed in a WorkOS environment are represented by events. These can occur as a result of user-related actions, manually via the WorkOS dashboard, or via API calls. To keep your app in sync with the latest directory data, follow the corresponding guides:
+
+- Learn about the different types of events that you can receive. See [event types](/events).
+- Handle the events you need on your side by syncing the data. See the [data syncing guide](/events/data-syncing).
+- Understand how directory events work. See the [understanding events guide](/directory-sync/understanding-events).
+- Optionally, stream events to Datadog. See the [observability guide](/events/observability/datadog).

package/.docs/organized/docs/directory-sync/understanding-events.mdx

@@ -0,0 +1,209 @@
+---
+title: Understanding the Events Lifecycle
+description: Understand the lifecycle of the events that occur in Directory Sync.
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/directory-sync/understanding-events.mdx
+---
+
+## Introduction
+
+Directory Sync events represent actions performed within directory providers. For example, an action could mean an IT admin assigning a user to your app or modifying a user group assigned to your app. These actions form the basis of user lifecycle management (ULM).
+
+WorkOS provides information about these actions through a set of structured events. This reference guide will cover the events Directory Sync produces and what they mean. To learn about how to handle these events on your side, see the [data syncing guide](/events/data-syncing).
+
+---
+
+## Directory events
+
+### `dsync.activated`
+
+This event occurs when you or your customer have successfully created a connection between WorkOS and your customer’s directory provider.
+
+- | Lifecycle
+
+  <DirectorySyncDiagram.DirectoryActivated />
+
+- | Payload
+
+  <CodeBlock title="Sample event object" file="event-dsync-activated" />
+
+`dsync.activated` is triggered if you manually create the directory connection in the [Developer Dashboard](https://dashboard.workos.com/), or your customer sets the connection up using the [Admin Portal](/admin-portal).
+
+The directory ID identifies a connection with the directory of a particular customer. Your app should save it and associate the directory ID with the corresponding organization ID.
+
+### `dsync.deleted`
+
+This event occurs when a Directory Sync connection is deleted in WorkOS, thus tearing down the link between your customer’s directory provider and your app.
+
+- | Lifecycle
+
+  <DirectorySyncDiagram.DirectoryDeleted />
+
+- | Payload
+
+  <CodeBlock title="Sample event object" file="event-dsync-deleted" />
+
+A connection can be deleted through the [Admin Portal](/admin-portal), [Developer Dashboard](https://dashboard.workos.com), or [WorkOS API](/reference/directory-sync/directory/delete). At this point your app should remove the association between the corresponding organization and its directory, as it no longer exists. Directories, users, and groups are typically deleted if your app offboards a customer altogether.
+
+When receiving a `dsync.deleted` event, you can ignore the connection’s `state` attribute, since it indicates the state before the deletion occurs. When a directory is deleted in WorkOS, a sole `dsync.deleted` event is sent.
+
+When a `dsync.deleted` event is received, it indicates that the users and groups in that directory have been deleted in WorkOS. You can process the `dsync.deleted` event accordingly in your application, removing the organization’s groups and its users from your application or marking them as deleted. `dsync.user.deleted` and `dsync.group.deleted` events will not be sent for the deleted directory.
+
+---
+
+## Directory user events
+
+### `dsync.user.created`
+
+This event occurs when an IT admin creates a user using their directory provider. It is standard to create and provision the user in your app when you receive this event.
+
+- | Lifecycle
+
+  <DirectorySyncDiagram.UserCreated />
+
+- | Payload
+
+  <CodeBlock title="Sample event object" file="event-dsync-user-created" />
+
+You can add this user to your users table in your app and associate them with the directory ID and organization ID. You can begin to engage with the user at this point, e.g., send the user a “Getting Started” email.
+
+During the initial sync of any directory, you will receive a `dsync.user.created` event for each existing user in the directory.
+
+### `dsync.user.updated`
+
+This event occurs when users’ attributes change. These attributes may be [standard attributes](/directory-sync/attributes/standard-attributes), [auto-mapped attributes](/directory-sync/attributes/custom-attributes/auto-mapped-attributes), or [custom-mapped attributes](/directory-sync/attributes/custom-attributes/custom-mapped-attributes).
+
+- | Lifecycle
+
+  <DirectorySyncDiagram.UserUpdated />
+
+- | Payload
+
+  <CodeBlock title="Sample event object" file="event-dsync-user-updated" />
+
+The payload for `dsync.user.updated` event shows changes between directory group snapshots in the `previous_attributes` property.
+
+The changes in the object are shallow differences for root properties, `raw_attributes`, and `custom_attributes`. If the current snapshot has a new attribute that did not exist previously, then the value for the attribute will be indicated as `null`.
+
+### `dsync.user.deleted`
+
+This event occurs when a user is hard-deleted from a directory. Typically, you would remove the user from your app in this case.
+
+- | Lifecycle
+
+  <DirectorySyncDiagram.UserDeleted />
+
+- | Payload
+
+  <CodeBlock title="Sample event object" file="event-dsync-user-deleted" />
+
+When users are removed from a directory, most providers will use a form of soft user deletion. In these cases, rather than receiving a `dsync.user.deleted` event, you will receive a `dsync.user.updated` event with the user’s `state` marked as `inactive`.
+
+> After Oct. 19, 2023, all new environments will delete Directory Users that get moved to the "inactive" state. If you would like to retain these users, please reach out to support. You can find [more details here](/directory-sync/handle-inactive-users).
+
+---
+
+## Directory group events
+
+### `dsync.group.created`
+
+This event occurs when creating a directory group in the directory provider. WorkOS also sends this event when a directory connection is established.
+
+- | Lifecycle
+
+  <DirectorySyncDiagram.GroupCreated />
+
+- | Payload
+
+  <CodeBlock title="Sample event object" file="event-dsync-group-created" />
+
+When WorkOS ingests this event, it first processes the users in the group. So, in most cases, you would receive `dsync.user.created`, then `dsync.group.created`, and finally, `dsync.group.user_added`.
+
+For more information on best practices for out-of-sequence events, see the [data syncing guide](/events/data-syncing).
+
+### `dsync.group.updated`
+
+This event is sent when an attribute of a directory group has changed.
+
+- | Lifecycle
+
+  <DirectorySyncDiagram.GroupUpdated />
+
+- | Payload
+
+  <CodeBlock title="Sample event object" file="event-dsync-group-updated" />
+
+The payload for `dsync.group.updated` events shows changes between directory group snapshots in the `previous_attributes` property.
+
+The changes in the object are shallow differences for root properties, `raw_attributes`, and `custom_attributes`. If the current snapshot has a new attribute that did not exist previously, then the value for the attribute will be indicated as `null`.
+
+### `dsync.group.deleted`
+
+This event occurs when deleting a directory group in the directory provider.
+
+When a `dsync.group.deleted` event is received, it indicates that the members in that group have been deleted in WorkOS. You can process the `dsync.group.deleted` event accordingly in your application, removing the group's members from your application or marking them as deleted. `dsync.group.user_removed` events will not be sent for the members in the deleted group.
+
+- | Lifecycle
+
+  <DirectorySyncDiagram.GroupDeleted />
+
+- | Payload
+
+  <CodeBlock title="Sample event object" file="event-dsync-group-deleted" />
+
+If your app relies on groups to sync users or map roles, you should remove access for the users who belonged to the deleted group.
+
+### `dsync.group.user_added`
+
+This event occurs when adding a directory user to a directory group.
+
+- | Lifecycle
+
+  <DirectorySyncDiagram.GroupUserAdded />
+
+- | Payload
+
+  <CodeBlock title="Sample event object" file="event-dsync-group-user-added" />
+
+If you map roles using groups, you should assign the group’s role to the newly added user.
+
+### `dsync.group.user_removed`
+
+This event occurs when removing a directory user from a directory group.
+
+- | Lifecycle
+
+  <DirectorySyncDiagram.GroupUserRemoved />
+
+- | Payload
+
+  <CodeBlock
+    title="Sample event object"
+    file="event-dsync-group-user-removed"
+  />
+
+If you map roles using groups, you should remove the group’s role from the user who belonged to the group.
+
+---
+
+## Data reconciliation techniques
+
+### With the WorkOS state API
+
+The WorkOS API allows for data reconciliation for your app. You can use the WorkOS API to pull the latest data to reconcile any data discrepancies between WorkOS and your app.
+
+A standard method apps use for data reconciliation is to set up a cron job that pulls from the WorkOS API on a consistent interval, e.g., every 1 to 6 hours, depending on your app’s user provisioning volume.
+
+> **Known issue:** Keeping track of WorkOS updated timestamps is of limited use right now because group membership changes for users do not alter the WorkOS `updated_at` timestamp. We're actively working on this issue.
+
+The general approach for performing a full sync of Directory Sync objects goes as follows:
+
+1. Traverse all directory groups and update all local objects.
+2. Traverse all directory users and update all local objects.
+3. Extract group membership information from each user. Compare with local membership state. Add and remove memberships accordingly.
+4. Compare the list of local users to all users seen in WorkOS traversal. Deactivate any users that exist locally but not on WorkOS.
+5. Compare the list of local groups to all groups seen on WorkOS traversal. Deactivate any groups that exist locally but not on WorkOS.
+
+### With the events API
+
+You can also reconcile directory data using the events API. See our [data syncing guide](/events/data-syncing/data-reconciliation) to learn more.

package/.docs/organized/docs/domain-verification/_navigation.mdx

@@ -0,0 +1,10 @@
+---
+title: Domain Verification
+links:
+  - title: Quick Start
+    url: /domain-verification
+  - title: API
+    url: /domain-verification/api
+originalPath: .tmp-workos-clone/packages/docs/content/domain-verification/_navigation.mdx
+---
+

package/.docs/organized/docs/domain-verification/api.mdx

@@ -0,0 +1,60 @@
+---
+title: API
+description: Programmatic domain verification
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/domain-verification/api.mdx
+---
+
+Instead of leveraging the Admin Portal, the Domain Verification API can be used to verify domains programmatically.
+
+Integrating with the API goes as follows:
+
+1. Create an Organization Domain for an Organization
+2. Share the token and setup instructions with the Organization owner (IT Admin)
+3. Wait for the verification to complete
+
+## Create a new Organization Domain
+
+All domains belong to an [Organization](/reference/organization). In order to create and verify a domain, an Organization must first be [created](/reference/organization/create).
+
+<CodeBlock title="Create an Organization Domain">
+  <CodeBlockTab title="Request" file="create-organization-domain" />
+  <CodeBlockTab title="Response" file="create-organization-domain-response" />
+</CodeBlock>
+
+The `verification_token` returned can then be set as the value of a TXT record that WorkOS will periodically check until the record is found. The TXT record for the above response example would be:
+
+- Name: `domain-to-verify.com`
+- Value: `verification_token=3CVZxo4HgvSiYRKlV4RdOWwWl`
+
+## Get a domain
+
+Fetch an existing domain and it’s current verification status. This endpoint can be polled once verification has been initiated to determine if verification has been successful.
+
+<CodeBlock title="Fetch an Organization Domain">
+  <CodeBlockTab title="Request" file="get-organization-domain" />
+  <CodeBlockTab title="Response" file="get-organization-domain-response" />
+</CodeBlock>
+
+Possible `state` values:
+
+- `pending`: domain verification has been initiated and not yet completed
+- `verified`: domain has been verified
+- `failed`: domain was not able to be verified
+
+Possible `verification_strategy` values:
+
+- `dns`: domain is verified with the DNS flow
+- `developer`: domain is verified by a person or a system, without running the DNS flow
+
+## Initiate verification for existing domain
+
+If a domain has not successfully verified within thirty days and moves to the `failed` state, verification can be restarted manually.
+
+<CodeBlock title="Verify an existing Organization Domain">
+  <CodeBlockTab title="Request" file="verify-existing-organization-domain" />
+  <CodeBlockTab
+    title="Response"
+    file="verify-existing-organization-domain-response"
+  />
+</CodeBlock>

package/.docs/organized/docs/domain-verification/index.mdx

@@ -0,0 +1,67 @@
+---
+title: Domain Verification
+description: Self-serve domain verification
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/domain-verification/index.mdx
+---
+
+# Introduction
+
+Domain Verification allows your customers to claim ownership of a domain. Once they have claimed ownership, features that require a higher level of trust and security can be activated.
+
+WorkOS Domain Verification provides a self-serve flow through the Admin Portal in which IT Admins can prove ownership through the creation of DNS TXT records.
+
+## Before getting started
+
+You’ll need a [WorkOS account](https://dashboard.workos.com/).
+
+### API object definitions
+
+[Organization](/reference/organization)
+: Describes an organization whose users sign in with a SSO Connection, or whose users are synced with a Directory Sync Connection.
+
+[Organization Domain](/reference/organization-domain)
+: Describes a domain associated to an organization, verified or unverified.
+
+[Portal Link](/reference/admin-portal/portal-link)
+: A temporary link to initiate an Admin Portal session. Valid for 5 minutes.
+
+All domains belong to an [Organization](/reference/organization). In order to create and verify a domain through the Admin Portal, an Organization must first be [created](/reference/organization/create).
+
+## (A) Setup link from the WorkOS dashboard
+
+- Sign in to your [WorksOS dashboard](https://dashboard.workos.com/) account and create or locate an Organization.
+- Click the “Invite Admin” button, select **Domain Verification** 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".
+
+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.
+
+![A screenshot showing the workOS dashboard admin invite.](https://images.workoscdn.com/images/c9196bbf-3860-4a9a-be8c-83b503ae4e3d.png?auto=format&fit=clip&q=80)
+
+## (B) Integrate with your app
+
+Admin Portal links can also be programmatically generated for the domain verification flow. This can be used to provide a link to the Admin Portal flow directly in your application.
+
+You’ll have to generate the link with the `domain_verification` intent:
+
+<CodeBlock
+  title="Create Admin Portal Link for Domain Verification"
+  file="create-admin-portal-link"
+/>
+
+Please refer to the [Admin Portal Integration Guide](/admin-portal/b-integrate-with-your-app) for additional integration details.
+
+---
+
+## Admin Portal domain verification
+
+After receiving the invitation and clicking on the setup link, the organization's admin is prompted to enter the domain they wish to verify.
+
+![A screenshot show the Admin portal domain entry form.](https://images.workoscdn.com/images/e7e719d6-579b-4567-8c80-772bc2f77563.png?auto=format&fit=clip&q=80)
+
+If the domain is valid, we identify the DNS service provider and offer custom setup instructions.
+
+The admin will find instruction to add a DNS TXT record with a token generated by our system.
+
+![A screenshot showing the Admin Portal domain DNS instructions.](https://images.workoscdn.com/images/9ab7e2a4-8b11-4a03-8203-d95d1c1abb07.png?auto=format&fit=clip&q=80)
+
+When we detect and verify the DNS record, we will mark the domain as `verified` and dispatch a [domain verification event](/events) to inform your application.