@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/authkit/_navigation.mdx

@@ -0,0 +1,108 @@
+---
+title: AuthKit
+links:
+  - title: Getting Started
+    links:
+      - title: Quick Start
+        url: /authkit
+      - title: CLI Installer
+        url: /authkit/cli-installer
+      - title: Example Apps
+        url: /authkit/example-apps
+  - title: Modeling Your App
+    links:
+      - title: Introduction and concepts
+        url: /authkit/modeling-your-app
+      - title: SSO with contractors
+        url: /authkit/sso-with-contractors
+      - title: Invite-only signup
+        url: /authkit/invite-only-signup
+  - title: Integrating
+    links:
+      - title: Users and Organizations
+        url: /authkit/users-organizations
+      - title: Hosted UI
+        url: /authkit/hosted-ui
+      - title: Sessions
+        url: /authkit/sessions
+      - title: Branding
+        url: /authkit/branding
+      - title: Migrations
+        url: /authkit/migrations
+      - title: Widgets
+        url: /widgets
+      - title: Actions
+        url: /authkit/actions
+      - title: MCP
+        url: /authkit/mcp
+      - title: On-prem Deployment
+        url: /on-prem-deployment
+  - title: Authentication
+    links:
+      - title: Single Sign-On
+        url: /authkit/sso
+      - title: Email + Password
+        url: /authkit/email-password
+      - title: Passkeys
+        url: /authkit/passkeys
+      - title: Social Login
+        url: /authkit/social-login
+      - title: Multi-Factor Auth
+        url: /authkit/mfa
+      - title: Magic Auth
+        url: /authkit/magic-auth
+      - title: CLI Auth
+        url: /authkit/cli-auth
+  - title: Features
+    links:
+      - title: API Keys
+        url: /authkit/api-keys
+      - title: Custom Emails
+        url: /authkit/custom-emails
+      - title: Custom Email Providers
+        url: /authkit/custom-email-providers
+      - title: Directory Provisioning
+        url: /authkit/directory-provisioning
+      - title: Domain Verification
+        url: /authkit/domain-verification
+      - title: Email Verification
+        url: /authkit/email-verification
+      - title: Identity Linking
+        url: /authkit/identity-linking
+      - title: Impersonation
+        url: /authkit/impersonation
+      - title: Invitations
+        url: /authkit/invitations
+      - title: JIT Provisioning
+        url: /authkit/jit-provisioning
+      - title: JWT Templates
+        url: /authkit/jwt-templates
+      - title: Metadata and External IDs
+        url: /authkit/metadata
+      - title: Organization Policies
+        url: /authkit/organization-policies
+      - title: Radar
+        url: /authkit/radar
+      - title: Roles and Permissions
+        url: /authkit/roles-and-permissions
+  - title: WorkOS Connect
+    links:
+      - title: Getting Started
+        url: /authkit/connect
+      - title: OAuth Applications
+        url: /authkit/connect/oauth
+      - title: M2M Applications
+        url: /authkit/connect/m2m
+      - title: Standalone
+        url: /authkit/connect/standalone
+  - title: Add-ons
+    links:
+      - title: Google Analytics
+        url: /authkit/add-ons/google-analytics
+      - title: Segment
+        url: /authkit/add-ons/segment
+      - title: Stripe
+        url: /authkit/add-ons/stripe
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/_navigation.mdx
+---
+

package/.docs/organized/docs/{user-management → authkit}/actions.mdx

@@ -2,8 +2,7 @@
 title: Actions
 description: Customize authentication flows with your own logic.
 showNextPage: true
-featureFlag: actions-docs
-originalPath: .tmp-workos-clone/packages/docs/content/user-management/actions.mdx
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/actions.mdx
 ---
 
 ## Introduction
@@ -23,7 +22,7 @@ WorkOS allows you to configure actions that execute during various user operatio
 
 To configure actions, you'll need to:
 
-- Host an actions endpoint that receive requests from WorkOS
+- Host an actions endpoint that receives requests from WorkOS
 - Register your endpoints with WorkOS
 - Implement the custom logic of your endpoint
 - Test your endpoints
@@ -57,7 +56,7 @@ Each actions endpoint must specify its error handling behavior. By default, if t
 
 Upon receiving a request, you should respond with an `HTTP 200 OK` as well as a valid response body to signal to WorkOS that the request was successfully handled.
 
-### (A) Validate the requests using the SDK
+### (A) Validate the requests using the SDK
 
 Before processing the request payload, verify the request was sent by WorkOS and not an unknown party.
 

package/.docs/organized/docs/authkit/add-ons/google-analytics.mdx

@@ -0,0 +1,79 @@
+---
+title: Google Analytics
+description: Track user activity on AuthKit pages in Google Analytics.
+icon: google-analytics
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/add-ons/google-analytics.mdx
+---
+
+## Introduction
+
+The Google Analytics AuthKit Add-on gives you data about logins, sign ups, and many other AuthKit activities inside of Google Analytics. You can use that data to better understand the effectiveness of your marketing campaigns and your users' full journeys across your website and AuthKit.
+
+---
+
+## Configuring the Add-on
+
+### (1) Confirm your domain
+
+To use the Add-on, your [Authentication API Domain](/custom-domains/auth-api) must share the same root as the domain where you set up Google Analytics through Google Tag Manager or gtag.js. This gives the Add-on access to your users' Google Analytics client IDs, which the Add-on uses to associate events in AuthKit with users from your website.
+
+For example, if your Google Analytics script lives at www.example.com:
+
+- **Valid:** auth.example.com is a valid Authentication API Domain
+- **Invalid:** auth.workos.com is not a valid Authentication API Domain
+
+### (2) Visit the Add-ons page
+
+In the WorkOS Dashboard, click the _Authentication_ icon in the sidebar. Then click _Add-ons_.
+
+![Add-ons page in the Authentication section of the WorkOS Dashboard](https://images.workoscdn.com/images/d5b867bb-8f04-440b-8443-4f9a1026a0cb.png?auto=format&fit=clip&q=50)
+
+### (3) Enable the Add-on
+
+Click _Enable_ next to _Google Analytics._
+
+![Google Analytics modal with Measurement ID and Measurement Protocol API Secret fields in the WorkOS Dashboard](https://images.workoscdn.com/images/40f61f05-32d2-4439-ae68-3c3b8f8aaf87.png?auto=format&fit=clip&q=50)
+
+In another browser tab, visit Google Analytics to get your credentials. Click the _Admin_ icon in the bottom left corner.
+
+![Admin icon on the Google Analytics website](https://images.workoscdn.com/images/21267275-4fde-431b-95d6-8e1ec3cc8190.png?auto=format&fit=clip&q=50)
+
+Under _Data collection and modification_, click _Data streams._
+
+![Data steams link on the Google Analytics website](https://images.workoscdn.com/images/8f967c62-d63f-4130-8510-dc97a249d0b4.png?auto=format&fit=clip&q=50)
+
+Click the data stream that you used to set up Google Analytics on your website. Under _Measurement ID_, click the copy icon. Paste your Measurement ID in the Measurement ID field in the WorkOS Dashboard.
+
+![Measurement ID on the Google Analytics website](https://images.workoscdn.com/images/68dbf576-dae1-4940-b3d4-6840086f94b5.png?auto=format&fit=clip&q=50)
+
+Under _Events_, click _Measurement Protocol API secrets_.
+
+![Measurement Protocol API Secrets section on the Google Analytics website](https://images.workoscdn.com/images/cdf958e3-6714-4700-9c77-71e46af96bc5.png?auto=format&fit=clip&q=50)
+
+Click _Create_. Give your new secret a name, like _WorkOS AuthKit_ _Add-on_. Copy the _Secret value._ The secret value may be cut off on narrower windows, so try double clicking the value before copying it to ensure you have selected the full value.
+
+![Measurement Protocol API Secret value on the Google Analytics website](https://images.workoscdn.com/images/8bd84bdf-eb85-4987-97a2-c13c863508a3.png?auto=format&fit=clip&q=50)
+
+Paste the secret value in the API Secret field in the WorkOS Dashboard. Click _Save changes_. The Google Analytics AuthKit Add-on is enabled and will begin sending AuthKit events to Google Analytics.
+
+![Google Analytics AuthKit Add-on enabled in the WorkOS Dashboard](https://images.workoscdn.com/images/0e47d2b4-29ad-4a47-9ab6-470dee7cc63c.png?auto=format&fit=clip&q=50)
+
+---
+
+## Events sent to Google Analytics
+
+The Add-on sends events to Google Analytics when certain [WorkOS Events](/events) occur:
+
+- `user.created` sends Google a [`sign_up` recommended event](https://developers.google.com/analytics/devguides/collection/ga4/reference/events?client_type=gtag#sign_up)
+- `authentication.magic_auth_succeeded`, `authentication.mfa_succeeded`, `authentication.oauth_succeeded`, `authentication.passkey_succeeded`, `authentication.password_succeeded`, and `authentication.sso_succeeded` send Google a [`login` recommended event](https://developers.google.com/analytics/devguides/collection/ga4/reference/events?client_type=gtag#login) including a `method` parameter matching the login method
+- The remaining _Authentication_ events, _Email verification_ events, _Magic Auth_ events, _Password reset_ events, and `session.created` send Google events based on the WorkOS event name, with underscores replacing periods
+- `authentication.email_verification_succeeded` is shortened to `auth_email_verification_succeeded` to meet Google's requirement that event names be 40 characters or shorter
+
+---
+
+## Verifying events
+
+After enabling the Add-on, visit your website, click your sign in button, and sign in to your application. Visit Google Analytics and click _Reports_ in the sidebar. Then click _Realtime overview_. Within five minutes, you should see a `login` event under _Event count by Event name_.
+
+If you do not see a login event, visit the Add-ons page in the WorkOS Dashboard to verify your Measurement ID and API Secret match the values from Google Analytics. If after confirming the values match you still need support, please reach out to us in Slack.

package/.docs/organized/docs/authkit/add-ons/segment.mdx

@@ -0,0 +1,77 @@
+---
+title: Segment
+description: Send AuthKit events to your Segment destinations.
+icon: segment
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/add-ons/segment.mdx
+---
+
+## Introduction
+
+The Segment AuthKit Add-on allows you to register AuthKit as a Segment source and receive events about logins, sign ups, and many other AuthKit activities. You can forward that data to your Segment destinations, allowing you to better understand the effectiveness of your marketing campaigns and your users' full journeys across your website and AuthKit.
+
+---
+
+## Configuring the Add-on
+
+### (1) Confirm your domain
+
+To use the Add-on, your [Authentication API Domain](/custom-domains/auth-api) must share the same root as the domain where you set up Segment through Analytics.js. This gives the Add-on access to your users' anonymous IDs, which the Add-on uses to identify users.
+
+For example, if your Segment Analytics.js script lives at www.example.com:
+
+- **Valid:** auth.example.com is a valid Authentication API Domain
+- **Invalid:** auth.workos.com is not a valid Authentication API Domain
+
+### (2) Visit the Add-ons page
+
+In the WorkOS Dashboard, click the _Authentication_ icon in the sidebar. Then click _Add-ons_.
+
+![Add-ons page in the Authentication section of the WorkOS Dashboard](https://images.workoscdn.com/images/d5b867bb-8f04-440b-8443-4f9a1026a0cb.png?auto=format&fit=clip&q=50)
+
+### (3) Enable the Add-on
+
+Click _Enable_ next to _Segment._
+
+![Segment modal containing a Write Key field in the WorkOS Dashboard](https://images.workoscdn.com/images/18d3da6b-0b59-4973-8a71-851e1ad4e5dc.png?auto=format&fit=clip&q=50)
+
+In another browser tab, visit Segment to get your credentials. Click _Connections_ in the left sidebar.
+
+![Connections link in Segment](https://images.workoscdn.com/images/78899ff2-be15-4fc0-a9d4-1482af04703e.png?auto=format&fit=clip&q=50)
+
+Next to _Sources_, click _Add more_.
+
+![Add more link on the Connections page in Segment](https://images.workoscdn.com/images/5feab1ce-89d3-4998-b16e-9ffdb48b4b0f.png?auto=format&fit=clip&q=50)
+
+Under _Choose a Source_, search "HTTP API." Below, click _HTTP API_. Then, in the lower right corner, click _Next._
+
+![HTTP API source in Segment](https://images.workoscdn.com/images/c6be5d31-307f-4371-82de-9486a034f478.png?auto=format&fit=clip&q=50)
+
+Under _Create your source_, give your source a name, like _WorkOS AuthKit Add-on_. Click _Create Source_. Under _Configure this source in your HTTP API codebase_, find your _Write Key_, and click the _Copy_ button next to it.
+
+![Copy button next to a new Write Key for an HTTP API source in Segment](https://images.workoscdn.com/images/82093be1-5a27-4985-bdef-ce3899832ee6.png?auto=format&fit=clip&q=50)
+
+Paste your write key in the _Write Key_ field in the WorkOS Dashboard. Click _Save changes_. The Segment AuthKit Add-on is enabled and will begin sending AuthKit events to Segment.
+
+---
+
+## Events sent to Segment
+
+The Add-on sends events to Segment when certain [WorkOS Events](/events) occur:
+
+- _Authentication_ events
+- _Email verification_ events
+- _Magic Auth_ events
+- _Password reset_ events
+- `session.created`
+- `user.created`
+
+All names of events in Segment will match the names of the [WorkOS Events](/events).
+
+---
+
+## Verifying events
+
+After enabling the Add-on, visit your website, click your sign in button, and sign in to your application. Visit Segment and click _Connections_ in the sidebar. Click the source you created. Then click the _Debugger_ tab. You should see an identify call including your anonymous ID and a track call with an authentication event.
+
+If you do not see an authentication event, visit the Add-ons page in the WorkOS Dashboard to verify your Write Key matches the value from Segment. If after confirming the values match you still need support, please reach out to us in Slack.

package/.docs/organized/docs/authkit/add-ons/stripe.mdx

@@ -0,0 +1,103 @@
+---
+title: Stripe
+description: >-
+  Connect your WorkOS account to Stripe to automatically provision access tokens
+  with entitlements and sync organization seat counts.
+icon: stripe
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/add-ons/stripe.mdx
+---
+
+## Introduction
+
+WorkOS provides two powerful Stripe integrations that help you manage billing and access control for your B2B application:
+
+- **Stripe Entitlements**: Automatically provision access tokens with subscription-based entitlements from Stripe
+- **Stripe Seat Sync**: Automatically sync organization member counts to Stripe billing meters for usage-based billing
+
+Both features use [Stripe Connect](https://stripe.com/connect) to connect your WorkOS account to your Stripe account, allowing WorkOS to manage these integrations on your behalf.
+
+---
+
+## Connect to Stripe
+
+To use either Stripe Entitlements or Stripe Seat Sync, you'll first need to connect your WorkOS account to Stripe using Stripe Connect.
+
+Navigate to the _Authentication_ section of the [WorkOS Dashboard](https://dashboard.workos.com/) and click _Add-ons_.
+
+From that page, find the Stripe Add-on and click _Enable_.
+
+![Authentication Add-ons page](https://images.workoscdn.com/images/75c987b7-d946-4e37-b46d-043fa994cfb4.png?auto=format&fit=clip&q=80)
+
+This will open a Dialog to pick the Stripe features you would like to use. When clicking _Continue_ you'll be directed to Stripe where you can approve the connection. Once that's complete, close the tab.
+
+> WorkOS does not currently support connecting to a Stripe Sandbox account. Connect WorkOS to a standard Stripe account, and use Stripe’s test mode for development and testing your integration.
+
+![Stripe Dialog](https://images.workoscdn.com/images/5953bd10-b966-4b1f-8d9f-7cd490bc19d3.png?auto=format&fit=clip&q=80)
+
+In the connection dialog, you can choose to enable one or both features:
+
+- **Use Stripe entitlements**: Include entitlement data in access tokens
+- **Sync organization seat counts**: Send member counts to Stripe billing meters
+
+If you decide to disconnect your Stripe account later or toggle features on and off, you can do so from the same section. Click the _Manage_ button to disable features or disconnect entirely.
+
+---
+
+## Set Stripe Customer IDs
+
+To use either of these features, you'll need to set the Stripe customer ID on each WorkOS organization.
+
+Once you have a WorkOS organization ID and a Stripe customer ID, you can set the Stripe customer ID for the organization. One way to handle this is to create a Stripe customer and then set the created Stripe customer ID on the WorkOS organization. This can be done via the WorkOS API or SDK. Here's an example using the SDK:
+
+<CodeBlock file="configure-organization-with-stripe-customer-id" />
+
+---
+
+## Stripe Entitlements
+
+Entitlements are a way to provision an account in your application with specific features or functionality based on the subscription plan a user is on. For example, you might have an "Enterprise" plan that allows users to access certain features like [Audit Logs](/audit-logs), and a "Basic" plan that does not.
+
+The WorkOS Entitlements integration makes it easy to get Stripe's entitlement information into your application without needing to listen to Stripe webhooks or explicitly track them in your application.
+
+### Use the entitlements in your application
+
+The access token will now include the `entitlements` claim, containing the user's entitlements. You can use this information to gate access to features in your application.
+
+> Entitlements added mid-cycle will appear in the next Stripe billing cycle or when a new subscription is created, per Stripe’s billing logic.
+
+Entitlements will show up in the access token the next time the user logs in or the session is refreshed. You can manually [refresh the session](/reference/authkit/authentication/refresh-token) after the user has completed their subscription purchase. Here's an example in Express:
+
+<CodeBlock file="session-entitlements-example" />
+
+---
+
+## Stripe Seat Sync
+
+Stripe Seat Sync automatically sends active organization member counts to Stripe as billing meter events under [Usage-based billing](https://docs.stripe.com/billing/subscriptions/usage-based), enabling usage-based billing based on the number of seats (members) in each organization.
+
+### How it works
+
+When Stripe Seat Sync is enabled:
+
+- WorkOS creates a billing meter in your Stripe account called **"User Seat Count"** with the event name `workos_seat_count`
+- Whenever a member is added, removed, deactivated, or activated from an organization, WorkOS automatically sends a meter event to Stripe with the updated seat count
+- You can use this meter in Stripe to create usage-based pricing based on the number of active seats
+
+The meter uses Stripe's ["last" aggregation method](https://docs.stripe.com/billing/subscriptions/usage-based/meters/configure), which means Stripe will bill based on the most recent seat count reported during each billing period.
+
+### Using the seat count meter in Stripe
+
+Once enabled, WorkOS will automatically send meter events to Stripe whenever organization memberships change. You can:
+
+- View the meter events in your Stripe Dashboard under **Billing → Meters**
+- Create pricing models that bill based on the `workos_seat_count` meter
+- Use the meter in subscription items to charge customers based on their current seat count
+
+The meter event includes:
+
+- **Event name**: `workos_seat_count`
+- **Customer ID**: The Stripe customer ID associated with the organization
+- **Value**: The current number of active members in the organization
+
+No additional code is required in your application—WorkOS handles all meter event reporting automatically as members join or leave organizations.

package/.docs/organized/docs/authkit/api-keys.mdx

@@ -0,0 +1,99 @@
+---
+title: API Keys
+description: 'Provide secure, self-service API key management to your customers.'
+showNextPage: true
+originalPath: .tmp-workos-clone/packages/docs/content/authkit/api-keys.mdx
+---
+
+## Introduction
+
+API keys provide a secure way for your application's users to authenticate with your API. With the [API Keys Widget](/widgets/api-keys), your customers can create and revoke [organization](/authkit/users-organizations/organizations)-scoped API keys with a simple component. The WorkOS API and SDKs provide functions for your API code to validate keys.
+
+API keys are one of two ways WorkOS enables you to issue credentials to your customers that they use to programmatically access your application. The other is [M2M applications](/authkit/connect/m2m). The [API Keys vs M2M Applications guide](https://workos.com/blog/api-keys-vs-m2m-applications) can help you decide which is best for your use case.
+
+## Configuring API keys
+
+Before your users can manage API keys, you need to configure your WorkOS environment.
+
+### Setting up role permissions
+
+To enable API key management for your users, ensure at least one role includes the `widgets:api-keys:manage` permission. This permission allows users to access the [API Keys Widget](/widgets/api-keys) and manage keys within their organization.
+
+You can [assign permissions to roles](/authkit/roles-and-permissions/configure-roles-and-permissions/assign-permissions-to-roles) in the WorkOS Dashboard under _Authorization_.
+
+### Configuring available permissions
+
+You can control which permissions your users can assign to API keys by configuring API key permissions in your environment.
+
+For example, you might create permissions like:
+
+- `posts:read` - Read access to posts
+- `posts:write` - Write access to posts
+- `users:read` - Read access to user data
+
+By configuring only `posts:read` and `posts:write` as available API key permissions, your users can create API keys with granular access controls, such as read-only keys that only have the `posts:read` permission.
+
+You can configure API key permissions in the WorkOS Dashboard under _Authorization > Configuration > Organization API key permissions_.
+
+## API key management in your application
+
+### Using the API Keys Widget
+
+The easiest way to enable API key management for your users is through the [API Keys Widget](/widgets/api-keys). This widget provides a complete interface for creating, viewing, and revoking API keys.
+
+The widget allows your users to:
+
+- Create new API keys with custom names
+- Select specific permissions for each key
+- View existing API keys (with obfuscated values for security)
+- Revoke API keys when they're no longer needed
+
+The widget interacts with the WorkOS API and renders the user interface in your app, so your customers get full control over their API keys in just a few lines of code.
+
+### Managing API keys via the API
+
+You can also manage API keys programmatically using the WorkOS API. This is useful for building custom API key management interfaces or automating key lifecycle operations.
+
+- [Create an API key](/reference/authkit/api-keys/create-for-organization) for an organization
+- [List API keys](/reference/authkit/api-keys/list-for-organization) for an organization
+- [Delete an API key](/reference/authkit/api-keys/delete)
+
+## Validating API keys
+
+Once API keys have been created, your application needs to validate these keys when they're used to authenticate API requests. When an API request includes an API key (typically in the `Authorization` header), your application should validate it with WorkOS to ensure it's legitimate and retrieve the associated permissions.
+
+The [validate API key endpoint](/reference/authkit/api-keys/validate) returns the complete [API key object](/reference/authkit/api-keys), including:
+
+- The organization that owns the key
+- The permissions assigned to the key
+- Usage metadata like creation and last-used timestamps
+
+This information allows your application to not only authenticate the request but also authorize it based on the specific permissions granted to that API key.
+
+<CodeBlock>
+  <CodeBlockTab file="api-keys-validate-nextjs" title="Next.js" language="js" />
+  <CodeBlockTab
+    file="api-keys-validate-express"
+    title="Express"
+    language="js"
+  />
+  <CodeBlockTab
+    file="api-keys-validate-flask"
+    title="Flask"
+    language="python"
+  />
+</CodeBlock>
+
+## Viewing organization API keys in the WorkOS Dashboard
+
+You can view and revoke your customers' API keys through the WorkOS Dashboard or [via the API](/reference/authkit/api-keys):
+
+1. Navigate to the **Organizations** section in your WorkOS Dashboard
+2. Click on the organization you want to view
+3. Select the **API Keys** tab
+
+From this view, you can see all API keys created by the organization, including their names, permissions, creation dates, and last usage information. This provides valuable visibility into how your customers are using API keys.
+
+## Auditing API key usage
+
+API key lifecycle changes are tracked via the [`api_key.created`](/events/api-key) and [`api_key.revoked`](/events/api-key) events. You can view these events in the [events page](https://dashboard.workos.com/environment/events) or listen for them in your application via the [events API](/events).