@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/reference/workos-connect/applications/list.mdx

@@ -0,0 +1,49 @@
+---
+descriptions:
+  list_connect_applications:
+    organization_id: Filter applications by organization ID.
+    data: Array of connect_application objects ordered by creation time.
+reference:
+  curl:
+    - key: list_connect_applications
+      type: GET
+      id: list_connect_applications
+      url: /reference/workos-connect/applications/list
+      title: /connect/applications
+      parameters:
+        - key: organization_id
+          optional: true
+          type: string
+          description: (list_connect_applications.organization_id)
+        - (limit)
+        - (before)
+        - (after)
+        - (order)
+      returns:
+        - key: list
+          type: object
+          unwrap: true
+          properties:
+            - key: object
+              type: string
+              description: Always "list"
+            - key: data
+              type: array
+              description: (list_connect_applications.data)
+            - key: list_metadata
+              type: object
+              properties:
+                - (before)
+                - (after)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/workos-connect/applications/list.mdx
+---
+
+## List Connect Applications
+
+List all Connect Applications in the current environment with optional filtering.
+
+<CodeBlock referenceId="list_connect_applications">
+  <CodeBlockTab title="Request" file="list-connect-applications-request" />
+  <CodeBlockTab title="Response" file="list-connect-applications-response" />
+</CodeBlock>

package/.docs/organized/docs/reference/workos-connect/applications/m2m.mdx

@@ -0,0 +1,52 @@
+---
+reference:
+  curl:
+    - url: /reference/workos-connect/applications/m2m
+      key: connect_application_m2m
+      id: connect_application_m2m
+      title: M2M Application
+      properties:
+        - key: object
+          type: '"connect_application"'
+          description: (connect_application.object)
+        - key: id
+          type: string
+          description: (connect_application.id)
+        - key: client_id
+          type: string
+          description: (connect_application.client_id)
+        - key: name
+          type: string
+          description: (connect_application.name)
+        - key: description
+          optional: true
+          type: string
+          description: (connect_application.description)
+        - key: application_type
+          type: '"m2m"'
+          description: (connect_application.application_type)
+        - key: organization_id
+          type: string
+          description: (connect_application.organization_id)
+        - key: scopes
+          type: 'string[]'
+          description: (connect_application.scopes)
+        - key: created_at
+          type: string
+          description: (connect_application.created_at)
+        - key: updated_at
+          type: string
+          description: (connect_application.updated_at)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/workos-connect/applications/m2m.mdx
+---
+
+## Machine-to-Machine Applications
+
+[M2M applications](/authkit/connect/m2m) are designed for server-to-server authentication without user interaction.
+
+<CodeBlock
+  title="M2M Application Example"
+  file="connect-application-m2m"
+  referenceId="connect_application_m2m"
+/>

package/.docs/organized/docs/reference/workos-connect/applications/oauth.mdx

@@ -0,0 +1,85 @@
+---
+reference:
+  curl:
+    - url: /reference/workos-connect/applications/oauth
+      key: connect_application_oauth
+      id: connect_application_oauth
+      title: OAuth Application
+      properties:
+        - key: object
+          type: '"connect_application"'
+          description: (connect_application.object)
+        - key: id
+          type: string
+          description: (connect_application.id)
+        - key: client_id
+          type: string
+          description: (connect_application.client_id)
+        - key: name
+          type: string
+          description: (connect_application.name)
+        - key: description
+          optional: true
+          type: string
+          description: (connect_application.description)
+        - key: application_type
+          type: '"oauth"'
+          description: (connect_application.application_type)
+        - key: redirect_uris
+          type: array
+          description: (connect_application.redirect_uris)
+          properties:
+            - key: uri
+              type: string
+              description: The redirect URI
+            - key: default
+              type: boolean
+              description: Whether this is the default redirect URI
+        - key: uses_pkce
+          type: boolean
+          description: (connect_application.uses_pkce)
+        - key: is_first_party
+          type: boolean
+          description: (connect_application.is_first_party)
+        - key: was_dynamically_registered
+          optional: true
+          type: boolean
+          description: (connect_application.was_dynamically_registered)
+        - key: organization_id
+          optional: true
+          type: string
+          description: (connect_application.organization_id)
+        - key: scopes
+          type: 'string[]'
+          description: (connect_application.scopes)
+        - key: created_at
+          type: string
+          description: (connect_application.created_at)
+        - key: updated_at
+          type: string
+          description: (connect_application.updated_at)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/workos-connect/applications/oauth.mdx
+---
+
+## OAuth Applications
+
+[OAuth applications](/authkit/connect/oauth) are designed for web, mobile, desktop, and CLI applications where a user needs to authenticate.
+
+<CodeBlock
+  title="OAuth Application Examples"
+  referenceId="connect_application_oauth"
+>
+  <CodeBlockTab
+    title="First-Party"
+    file="connect-application-oauth-first-party"
+  />
+  <CodeBlockTab
+    title="Third-Party"
+    file="connect-application-oauth-third-party"
+  />
+  <CodeBlockTab
+    title="Dynamically Registered"
+    file="connect-application-oauth-dynamically-registered"
+  />
+</CodeBlock>

package/.docs/organized/docs/reference/workos-connect/applications/update.mdx

@@ -0,0 +1,59 @@
+---
+descriptions:
+  update_connect_application:
+    id_parameter: The application ID or client ID.
+    name: Updated name of the application.
+    description: Updated description. Pass null to clear.
+    scopes: Updated permission slugs.
+    redirect_uris: Updated redirect URIs. OAuth applications only.
+reference:
+  curl:
+    - key: update_connect_application
+      type: PUT
+      id: update_connect_application
+      url: /reference/workos-connect/applications/update
+      title: '/connect/applications/:id'
+      parameters:
+        - key: id
+          type: string
+          description: (update_connect_application.id_parameter)
+        - key: name
+          optional: true
+          type: string
+          description: (update_connect_application.name)
+        - key: description
+          optional: true
+          type: string | null
+          description: (update_connect_application.description)
+        - key: scopes
+          optional: true
+          type: 'string[]'
+          description: (update_connect_application.scopes)
+        - key: redirect_uris
+          optional: true
+          type: array
+          description: (update_connect_application.redirect_uris)
+          properties:
+            - key: uri
+              type: string
+              description: The redirect URI
+            - key: default
+              optional: true
+              type: boolean
+              description: Whether this is the default redirect URI
+      returns:
+        - key: connect_application
+          type: object
+          description: The updated connect_application object
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/workos-connect/applications/update.mdx
+---
+
+## Update a Connect Application
+
+Update an existing Connect Application. For OAuth applications, you can update redirect URIs. For all applications, you can update the name, description, and scopes.
+
+<CodeBlock referenceId="update_connect_application">
+  <CodeBlockTab title="Request" file="update-connect-application-request" />
+  <CodeBlockTab title="Response" file="update-connect-application-response" />
+</CodeBlock>

package/.docs/organized/docs/reference/workos-connect/authorize/index.mdx

@@ -27,6 +27,26 @@ descriptions:
     state: >
       An opaque string used by the client to maintain state between the request
       and callback.
+    code_challenge: >
+      A code challenge used for PKCE (Proof Key for Code Exchange). This should
+      be a cryptographically
+
+      random string, encoded using the given `code_challenge_method`.
+
+
+      **Note:** PKCE is only supported by applications created through Dynamic
+      Client Registration,
+
+      which is required to use MCP (Model Context Protocol) authorization. For
+      setup instructions,
+
+      see our [MCP guide](/authkit/mcp).
+    code_challenge_method: >
+      The method used to encode the `code_challenge`. Currently, only `S256` is
+      supported, which means
+
+      the `code_challenge` is a Base64url-encoded SHA256 hash of the
+      `code_verifier`.
   workos_connect_authorize_response:
     url: |
       The OAuth 2.0 authorization URL to redirect the user to.
@@ -57,6 +77,14 @@ reference:
           type: string
           description: (workos_connect_authorize.state)
           optional: true
+        - key: code_challenge
+          type: string
+          description: (workos_connect_authorize.code_challenge)
+          optional: true
+        - key: code_challenge_method
+          type: '"S256"'
+          description: (workos_connect_authorize.code_challenge_method)
+          optional: true
       returns:
         - key: url
           type: string
@@ -65,7 +93,7 @@ originalPath: >-
   .tmp-workos-clone/packages/docs/content/reference/workos-connect/authorize/index.mdx
 ---
 
-## Authorize
+# Authorize
 
 When authenticating a user for a WorkOS Connect application, this is the endpoint they should be redirected to. If they’re not already logged in, the user will be redirected to the AuthKit login page. For a third-party application, the user will have to authorize the application’s access on their first access.
 

package/.docs/organized/docs/reference/workos-connect/cli-auth/authorize-device/index.mdx

@@ -0,0 +1,81 @@
+---
+descriptions:
+  workos_connect_device_authorize:
+    client_id: |
+      The client ID of the WorkOS Connect Application.
+    scope: |
+      A space-separated list of scopes being requested.
+
+      Acceptable values:
+      - `openid`: Required to enable other scopes like `profile` and `email`.
+      - `profile`: Adds profile information (name fields) to the ID token.
+        - `name`
+        - `given_name`
+        - `family_name`
+      - `email`: Adds email information to the ID token.
+        - `email`
+        - `email_verified`
+      - `offline_access`: Adds a refresh token to the response.
+  workos_connect_device_authorize_response:
+    device_code: >
+      A unique identifier for this authorization request. Use this when polling
+      the token endpoint.
+    user_code: |
+      A short, user-friendly code that users enter to authorize the device.
+    verification_uri: |
+      The URL where users can enter the user code to authorize the device.
+    verification_uri_complete: |
+      A URL with the user code pre-filled, allowing one-click authorization.
+    expires_in: >
+      The lifetime of the device code and user code in seconds (300 seconds = 5
+      minutes).
+    interval: |
+      The minimum interval in seconds between token requests (5 seconds).
+reference:
+  curl:
+    - url: /reference/workos-connect/cli-auth/authorize-device
+      key: workos_connect_device_authorize
+      id: workos_connect_device_authorize
+      title: /oauth2/device_authorization
+      type: POST
+      parameters:
+        - key: client_id
+          type: string
+          description: (workos_connect_device_authorize.client_id)
+        - key: scope
+          type: string
+          description: (workos_connect_device_authorize.scope)
+          optional: true
+      returns:
+        - key: device_code
+          type: string
+          description: (workos_connect_device_authorize_response.device_code)
+        - key: user_code
+          type: string
+          description: (workos_connect_device_authorize_response.user_code)
+        - key: verification_uri
+          type: string
+          description: (workos_connect_device_authorize_response.verification_uri)
+        - key: verification_uri_complete
+          type: string
+          description: (workos_connect_device_authorize_response.verification_uri_complete)
+        - key: expires_in
+          type: integer
+          description: (workos_connect_device_authorize_response.expires_in)
+        - key: interval
+          type: integer
+          description: (workos_connect_device_authorize_response.interval)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/workos-connect/cli-auth/authorize-device/index.mdx
+---
+
+# Authorize device
+
+Initiates the device authorization flow for WorkOS Connect applications. This endpoint implements the [OAuth 2.0 Device Authorization Flow](https://datatracker.ietf.org/doc/html/rfc8628) and is designed for CLI applications and other devices with limited input capabilities.
+
+This endpoint is used by third-party applications to authenticate users through WorkOS Connect. Users will be prompted to authorize the application's access to their data as part of the consent flow.
+
+<CodeBlock referenceId="workos_connect_device_authorize">
+  <CodeBlockTab title="Request" file="authorize-device-request" />
+  <CodeBlockTab title="Response" file="authorize-device-response" />
+</CodeBlock>

package/.docs/organized/docs/reference/workos-connect/cli-auth/device-code-grant.mdx

@@ -0,0 +1,74 @@
+---
+descriptions:
+  workos_connect_token_device_code_request:
+    grant_type: >
+      Must be `urn:ietf:params:oauth:grant-type:device_code` for device
+      authorization flow.
+    device_code: |
+      The device code obtained from the device authorization endpoint.
+    client_id: |
+      The client ID of the WorkOS Connect Application.
+    client_secret: |
+      A secret key associated with the WorkOS Connect Application.
+  workos_connect_token_device_code_response:
+    access_token: |
+      A JWT that can be used to authorize requests.
+    refresh_token: >
+      An opaque token that can be exchanged for new access, ID, and refresh
+      tokens.
+    id_token: |
+      A JWT that contains information about the user.
+    token_type: |
+      How to use the access token to authorize requests. Always `"Bearer"`.
+    expires_in: |
+      The number of seconds until the access token expires.
+reference:
+  curl:
+    - url: /reference/workos-connect/cli-auth/device-code-grant
+      key: workos_connect_token_device_code
+      id: workos_connect_token_device_code
+      title: /oauth2/token
+      type: POST
+      parameters:
+        - key: grant_type
+          type: '"urn:ietf:params:oauth:grant-type:device_code"'
+          description: (workos_connect_token_device_code_request.grant_type)
+        - key: device_code
+          type: string
+          description: (workos_connect_token_device_code_request.device_code)
+        - key: client_id
+          type: string
+          description: (workos_connect_token_device_code_request.client_id)
+        - key: client_secret?
+          type: string
+          description: (workos_connect_token_device_code_request.client_secret)
+      returns:
+        - key: access_token
+          type: string
+          description: (workos_connect_token_device_code_response.access_token)
+        - key: refresh_token
+          type: string
+          description: (workos_connect_token_device_code_response.refresh_token)
+        - key: id_token
+          type: string
+          description: (workos_connect_token_device_code_response.id_token)
+        - key: token_type
+          type: '"Bearer"'
+          description: (workos_connect_token_device_code_response.token_type)
+        - key: expires_in
+          type: integer
+          description: (workos_connect_token_device_code_response.expires_in)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/workos-connect/cli-auth/device-code-grant.mdx
+---
+
+## Device code grant
+
+Exchanges a device code for access and refresh tokens as part of the device authorization flow for WorkOS Connect applications. This endpoint should be polled repeatedly until the user authorizes the request, declines it, or the device code expires.
+
+<CodeBlock referenceId="workos_connect_token_device_code">
+  <CodeBlockTab title="Request" file="device-code-grant-request" />
+  <CodeBlockTab title="Response" file="device-code-grant-response" />
+</CodeBlock>
+
+The returned tokens are similar to those provided by the [authorization code grant](/reference/workos-connect/token/authorization-code-grant).

package/.docs/organized/docs/reference/workos-connect/cli-auth/index.mdx

@@ -0,0 +1,23 @@
+---
+descriptions:
+  cli_auth_connect:
+    device_code: >-
+      A unique identifier for the authorization request used when polling the
+      token endpoint.
+    user_code: 'A short, user-friendly code that users enter to authorize the device.'
+    verification_uri: The URL where users can enter the user code to authorize the device.
+    verification_uri_complete: A URL with the user code pre-filled for one-click authorization.
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/workos-connect/cli-auth/index.mdx
+---
+
+# CLI Auth
+
+CLI Auth for WorkOS Connect enables third-party applications to build command-line tools that integrate with your app's credentials using the [OAuth 2.0 Device Authorization Flow](https://datatracker.ietf.org/doc/html/rfc8628).
+
+The CLI Auth flow for Connect involves two main endpoints:
+
+1. The **device authorization URL** initiates the flow by obtaining device codes, user codes, and verification URIs.
+2. The **device access token URL** is where the device exchanges the device code for access and refresh tokens after the user authenticates.
+
+Read more about [CLI Auth here](/authkit/cli-auth/connect).

package/.docs/organized/docs/reference/workos-connect/index.mdx

@@ -30,4 +30,4 @@ originalPath: .tmp-workos-clone/packages/docs/content/reference/workos-connect/i
 
 WorkOS Connect is a unified interface that simplifies authentication and authorization across customers, partners, and external SaaS tools.
 
-Read more about [how Connect integrates with AuthKit here](/user-management/connect).
+Read more about [how Connect integrates with AuthKit here](/authkit/connect).

package/.docs/organized/docs/reference/workos-connect/introspection/index.mdx

@@ -18,8 +18,13 @@ descriptions:
       Identifies the consent previously given by the user. Only present for
       OAuth Application access tokens.
     org_id: >
-      For an M2M token, this is the identifier of the associated
-      [Organization](/reference/organization).
+      For an [OAuth](/authkit/connect/oauth/organization-access) token, this is
+      ID of the [Organization](/reference/organization) the user selected during
+      sign-in or on the third-party application authorization screen.
+
+
+      For an [M2M](/authkit/connect/m2m/organization-based-access-control)
+      token, this is the ID of the owning Organization.
     jti: >
       A unique identifer for the token. Only present for OAuth Application
       access tokens.
@@ -95,7 +100,7 @@ originalPath: >-
   .tmp-workos-clone/packages/docs/content/reference/workos-connect/introspection/index.mdx
 ---
 
-## Token introspection
+# Token introspection
 
 Indicates whether the given token (access token or refresh token) is valid and active. Additionally, it provides details about the token.
 

package/.docs/organized/docs/reference/workos-connect/metadata/index.mdx

@@ -20,6 +20,6 @@ originalPath: >-
   .tmp-workos-clone/packages/docs/content/reference/workos-connect/metadata/index.mdx
 ---
 
-## Metadata
+# Metadata
 
 Connect exposes several metadata endpoints in order to be compatible with a wide array of clients that support discovery and automatic configuration.

package/.docs/organized/docs/reference/workos-connect/metadata/oauth-authorization-server/index.mdx

@@ -85,7 +85,7 @@ originalPath: >-
 
 This endpoint provides [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)-compatible OAuth Authorization Server metadata.
 
-Model Context Protocol (MCP) clients that support the latest version of the specification use this endpoint. [Read more here](/user-management/mcp) about how to use AuthKit as an authorization server for an MCP server.
+Model Context Protocol (MCP) clients that support the latest version of the specification use this endpoint. [Read more here](/authkit/mcp) about how to use AuthKit as an authorization server for an MCP server.
 
 <CodeBlock referenceId="connect_oauth_authorization_server_metadata">
   <CodeBlockTab

package/.docs/organized/docs/reference/workos-connect/standalone/complete.mdx

@@ -0,0 +1,68 @@
+---
+reference:
+  curl:
+    - url: /reference/workos-connect/standalone/complete
+      key: authkit_standalone_complete
+      id: authkit_standalone_complete
+      title: /authkit/oauth2/complete
+      type: POST
+      parameters:
+        - key: external_auth_id
+          type: string
+          description: Identifier provided when AuthKit redirected to your login page.
+        - key: user
+          type: object
+          description: Authenticated user information.
+          properties:
+            - key: id
+              type: string
+              description: |
+                Your application's user identifier, which will be stored as an
+                [`external_id`](/authkit/metadata/external-identifiers). Used
+                for upserting and deduplication.
+            - key: email
+              type: string
+              description: (user.email)
+            - key: first_name
+              type: string
+              optional: true
+              description: (user.first_name)
+            - key: last_name
+              type: string
+              optional: true
+              description: (user.last_name)
+            - key: metadata
+              type: object
+              optional: true
+              description: (user.metadata)
+        - key: user_consent_options
+          type: array
+          optional: true
+          description: >-
+            Array of [User Consent
+            Options](/reference/workos-connect/standalone/user-consent-options).
+      returns:
+        - key: redirect_uri
+          type: string
+          description: URI to redirect the user back to AuthKit to complete the OAuth flow
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/workos-connect/standalone/complete.mdx
+---
+
+## Complete external authentication
+
+Completes an external authentication flow and returns control to AuthKit. This endpoint is used with [Standalone Connect](/authkit/connect/standalone) to bridge your existing authentication system with the Connect OAuth API infrastructure.
+
+After successfully authenticating a user in your application, calling this endpoint will:
+
+- Create or update the user in AuthKit, using the given `id` as its `external_id`.
+- Return a `redirect_uri` your application should redirect to in order for AuthKit to complete the flow
+
+Users are automatically created or updated based on the `id` and `email` provided. If a user with the same `id` exists, their information is updated. Otherwise, a new user is created.
+
+If you provide a new `id` with an `email` that already belongs to an existing user, the request will fail with an error as email addresses are unique to a user.
+
+<CodeBlock referenceId="authkit_standalone_complete">
+  <CodeBlockTab title="Request" file="complete-external-auth-request" />
+  <CodeBlockTab title="Response" file="complete-external-auth-response" />
+</CodeBlock>

package/.docs/organized/docs/reference/workos-connect/standalone/index.mdx

@@ -0,0 +1,9 @@
+---
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/workos-connect/standalone/index.mdx
+---
+# Standalone Connect
+
+Standalone Connect allows applications with existing authentication systems to use AuthKit as their OAuth authorization server. Instead of migrating your entire authentication stack, you can leverage WorkOS's OAuth infrastructure while keeping your existing user authentication as the source of truth.
+
+Read more in the [Standalone Connect guide](/authkit/connect/standalone).

package/.docs/organized/docs/reference/workos-connect/standalone/user-consent-options.mdx

@@ -0,0 +1,41 @@
+---
+reference:
+  curl:
+    - url: /reference/workos-connect/standalone/user-consent-options
+      key: authkit_standalone_user_consent_options
+      id: authkit_standalone_user_consent_options
+      title: User Consent Options
+      properties:
+        - key: claim
+          type: string
+          description: The claim name that will appear in the token.
+        - key: type
+          type: '"enum"'
+          description: Always `enum` (currently the only supported type).
+        - key: label
+          type: string
+          description: Display text for the option.
+        - key: choices
+          type: array
+          description: Array of choices. See the flat and grouped examples.
+          properties:
+            - key: label
+              type: string
+              description: Display text for the value.
+            - key: value
+              type: string
+              description: The value that will appear in the claim if selected.
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/workos-connect/standalone/user-consent-options.mdx
+---
+
+## User Consent Options
+
+The `user_consent_options` can take an array of consent options that the user will be required to choose from on AuthKit's OAuth consent screen. The chosen option will then become available as a JWT claim on the issued access token.
+
+These options can be presented as either a flat or grouped set of options.
+
+<CodeBlock referenceId="authkit_standalone_user_consent_options">
+  <CodeBlockTab title="Flat" file="user-consent-choice-flat" />
+  <CodeBlockTab title="Grouped" file="user-consent-choice-grouped" />
+</CodeBlock>

package/.docs/organized/docs/reference/workos-connect/token/authorization-code-grant/access-token.mdx

@@ -19,6 +19,12 @@ reference:
         - key: sub
           type: string
           description: (user.id)
+        - key: org_id
+          type: string
+          description: >
+            The ID of the Organization the user selected during sign-in or on
+            the third-party application authorization screen.
+          optional: true
         - key: sid
           type: string
           description: >