@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/reference/user-management/authentication/totp.mdx

@@ -0,0 +1,369 @@
+---
+descriptions:
+  authentication:
+    totp_code: >-
+      The time-based one-time password generated by the factor that was
+      challenged.
+    challenge_id: >-
+      The unique ID of the authentication challenge created for the TOTP factor
+      for which the user is enrolled.
+reference:
+  curl:
+    - key: authenticate_mfa_totp
+      id: authenticate_mfa_totp
+      url: /reference/user-management/authentication/mfa-totp
+      title: /user_management/authenticate
+      type: POST
+      parameters:
+        - key: client_id
+          type: string
+          description: (client_id)
+        - key: client_secret
+          type: string
+          description: (client_secret)
+        - key: grant_type
+          type: '"urn:workos:oauth:grant-type:mfa-totp"'
+          description: (authentication.grant_type)
+        - key: code
+          type: string
+          description: (authentication.totp_code)
+        - key: authentication_challenge_id
+          type: string
+          description: (authentication.challenge_id)
+        - key: pending_authentication_token
+          type: string
+          description: (authentication.pending_authentication_token)
+        - key: ip_address
+          type: string
+          optional: true
+          description: (authentication.ip_address)
+        - key: user_agent
+          type: string
+          optional: true
+          description: (authentication.user_agent)
+      returns:
+        - key: anonymous
+          type: object
+          unwrap: true
+          properties:
+            - key: user
+              type: user
+              description: (user.self)
+            - key: organizationId
+              type: string
+              optional: true
+              description: (authentication.organization_id)
+            - key: authentication_method
+              type: >-
+                "SSO" | "Password" | "AppleOAuth" | "GitHubOAuth" |
+                "GoogleOAuth" | "MicrosoftOAuth" | "MagicAuth" | "Impersonation"
+              optional: false
+              description: (authentication.authentication_method)
+  js:
+    - key: authenticateWithTotp
+      id: authenticate_mfa_totp
+      url: /reference/user-management/authentication/mfa-totp
+      title: userManagement.authenticateWithTotp()
+      parameters:
+        - key: clientId
+          type: string
+          description: (client_id)
+        - key: code
+          type: string
+          description: (authentication.totp_code)
+        - key: authenticationChallengeId
+          type: string
+          description: (authentication.challenge_id)
+        - key: pendingAuthenticationToken
+          type: string
+          description: (authentication.pending_authentication_token)
+        - key: ipAddress
+          type: string
+          optional: true
+          description: (authentication.ip_address)
+        - key: userAgent
+          type: string
+          optional: true
+          description: (authentication.user_agent)
+        - key: session
+          type: object
+          optional: true
+          unwrap: true
+          properties:
+            - key: sealSession
+              type: boolean
+              description: (authentication.seal_session)
+            - key: cookiePassword
+              type: string
+              optional: true
+              description: (authentication.cookie_password_seal)
+      returns:
+        - key: anonymous
+          type: object
+          unwrap: true
+          properties:
+            - key: user
+              type: User
+              description: (user.self)
+            - key: organizationId
+              type: string
+              optional: true
+              description: (authentication.organization_id)
+            - key: authenticationMethod
+              type: >-
+                "SSO" | "Password" | "AppleOAuth" | "GitHubOAuth" |
+                "GoogleOAuth" | "MicrosoftOAuth" | "MagicAuth" | "Impersonation"
+              optional: false
+              description: (authentication.authentication_method)
+            - key: sealedSession
+              type: string
+              optional: true
+              description: (authentication.sealed_session)
+  python:
+    - key: authenticate_with_totp
+      id: authenticate_mfa_totp
+      url: /reference/user-management/authentication/mfa-totp
+      title: user_management.authenticate_with_totp()
+      parameters:
+        - key: code
+          type: str
+          description: (authentication.totp_code)
+        - key: authentication_challenge_id
+          type: str
+          description: (authentication.challenge_id)
+        - key: pending_authentication_token
+          type: str
+          description: (authentication.pending_authentication_token)
+        - key: ip_address
+          type: str
+          optional: true
+          description: (authentication.ip_address)
+        - key: user_agent
+          type: str
+          optional: true
+          description: (authentication.user_agent)
+      returns:
+        - key: anonymous
+          type: AuthenticationResponse
+          unwrap: true
+          properties:
+            - key: user
+              type: User
+              description: (user.self)
+            - key: organization_id
+              type: str
+              optional: true
+              description: (authentication.organization_id)
+            - key: access_token
+              type: str
+              optional: false
+              description: (authentication.access_token)
+            - key: refresh_token
+              type: str
+              optional: false
+              description: (authentication.refresh_token)
+  go:
+    - key: AuthenticateWithTOTP
+      id: authenticate_mfa_totp
+      url: /reference/user-management/authentication/magic-totp
+      title: usermanagement.AuthenticateWithTOTP()
+      parameters:
+        - (ctx)
+        - key: opts
+          type: usermanagement.AuthenticateWithTOTPOpts
+          unwrap: true
+          properties:
+            - key: ClientID
+              type: string
+              description: (client_id)
+            - key: Code
+              type: string
+              description: (authentication.totp_code)
+            - key: AuthenticationChallengeID
+              type: string
+              description: (authentication.challenge_id)
+            - key: PendingAuthenticationToken
+              type: string
+              description: (authentication.pending_authentication_token)
+            - key: IPAddress
+              type: string
+              optional: true
+              description: (authentication.ip_address)
+            - key: UserAgent
+              type: string
+              optional: true
+              description: (authentication.user_agent)
+      returns:
+        - key: response
+          type: object
+          unwrap: true
+          properties:
+            - key: User
+              type: User
+              description: (user.self)
+            - key: OrganizationID
+              type: string
+              optional: true
+              description: (authentication.organization_id)
+        - (err)
+  php:
+    - key: authenticateWithTotp
+      id: authenticate_mfa_totp
+      url: /reference/user-management/authentication/mfa-totp
+      title: $userManagement->authenticateWithTotp()
+      parameters:
+        - key: clientId
+          type: string
+          description: (client_id)
+        - key: code
+          type: string
+          description: (authentication.totp_code)
+        - key: authenticationChallengeId
+          type: string
+          description: (authentication.challenge_id)
+        - key: pendingAuthenticationToken
+          type: string
+          description: (authentication.pending_authentication_token)
+        - key: ipAddress
+          type: string
+          optional: true
+          description: (authentication.ip_address)
+        - key: userAgent
+          type: string
+          optional: true
+          description: (authentication.user_agent)
+      returns:
+        - key: anonymous
+          type: object
+          unwrap: true
+          properties:
+            - key: user
+              type: User
+              description: (user.self)
+            - key: organizationId
+              type: string
+              optional: true
+              description: (authentication.organization_id)
+  ruby:
+    - key: authenticate_with_totp
+      id: authenticate_mfa_totp
+      url: /reference/user-management/authentication/mfa-totp
+      title: UserManagement.authenticate_with_totp()
+      parameters:
+        - key: client_id
+          type: String
+          description: (client_id)
+        - key: code
+          type: String
+          description: (authentication.totp_code)
+        - key: authentication_challenge_id
+          type: String
+          description: (authentication.challenge_id)
+        - key: pending_authentication_token
+          type: String
+          description: (authentication.pending_authentication_token)
+        - key: ip_address
+          type: String
+          optional: true
+          description: (authentication.ip_address)
+        - key: user_agent
+          type: String
+          optional: true
+          description: (authentication.user_agent)
+      returns:
+        - key: anonymous
+          type: object
+          unwrap: true
+          properties:
+            - key: user
+              type: User
+              description: (user.self)
+            - key: organization_id
+              type: String
+              optional: true
+              description: (authentication.organization_id)
+  java:
+    - key: authenticateWithTotp
+      id: authenticate_mfa_totp
+      url: /reference/user-management/authentication/mfa-totp
+      title: userManagement.authenticateWithTotp()
+      parameters:
+        - key: clientId
+          type: String
+          description: (client_id)
+        - key: code
+          type: String
+          description: (authentication.totp_code)
+        - key: authenticationChallengeId
+          type: String
+          description: (authentication.challenge_id)
+        - key: pendingAuthentication_Token
+          type: String
+          description: (authentication.pending_authentication_token)
+        - key: options
+          type: AuthenticationAdditionalOptionsBuilder
+          optional: true
+          unwrap: true
+          properties:
+            - key: invitationToken
+              type: String
+              optional: true
+              description: (authentication.invitation_token)
+            - key: ipAddress
+              type: String
+              optional: true
+              description: (authentication.ip_address)
+            - key: userAgent
+              type: String
+              optional: true
+              description: (authentication.user_agent)
+      returns:
+        - key: response
+          type: Authentication
+          unwrap: true
+          properties:
+            - key: user
+              type: User
+              optional: true
+              description: (user.self)
+            - key: organizationId
+              type: String
+              optional: true
+              description: (authentication.organization_id)
+            - key: accessToken
+              type: string
+              optional: true
+              description: (authentication.access_token)
+            - key: refreshToken
+              type: string
+              optional: true
+              description: (authentication.refresh_token)
+            - key: impersonator
+              type: AuthenticationImpersonator
+              optional: true
+              properties:
+                - key: email
+                  type: String
+                  description: (authentication.impersonator.email)
+                - key: reason
+                  type: String
+                  optional: true
+                  description: (authentication.impersonator.reason)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/user-management/authentication/totp.mdx
+---
+
+## Authenticate with a time-based one-time password
+
+Authenticates a user enrolled into MFA using time-based one-time password (TOTP).
+
+Users enrolled into MFA are required to enter a TOTP each time they sign in. When they attempt to authenticate with their credentials, the API will return an [MFA challenge error](/reference/user-management/authentication-errors/mfa-challenge-error) that contains a pending authentication token.
+
+To continue with the authentication flow, [challenge](/reference/mfa/challenge-factor) one of the factors returned by the MFA challenge error response and present a UI to the user to enter the TOTP code. Then, authenticate the user with the TOTP code, the challenge from the factor, and the pending authentication token from the MFA challenge error.
+
+MFA can be enabled via the [Authentication page](https://dashboard.workos.com/authentication) in the WorkOS dashboard.
+
+<CodeBlock referenceId="authenticate_mfa_totp">
+  <CodeBlockTab title="Request" file="authenticate-mfa-totp-request" />
+  <CodeBlockTab title="Response" file="authenticate-mfa-totp-response" />
+</CodeBlock>

package/.docs/organized/docs/reference/user-management/authentication-errors/email-verification-required-error.mdx

@@ -0,0 +1,42 @@
+---
+reference:
+  json:
+    - key: email_verification_required_error
+      id: email_verification_required_error
+      url: >-
+        /reference/user-management/authentication-errors/email-verification-required-error
+      title: email_verification_required
+      sendsEmail: true
+      properties:
+        - key: code
+          type: '"email_verification_required"'
+          description: (authentication_errors.code)
+        - key: message
+          type: string
+          description: (authentication_errors.message)
+        - key: pending_authentication_token
+          type: string
+          description: (authentication_errors.pending_authentication_token)
+        - key: email
+          type: string
+          description: (user.email)
+        - key: email_verification_id
+          type: string
+          description: (email_verification.id)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/user-management/authentication-errors/email-verification-required-error.mdx
+---
+
+## Email verification required error
+
+This error indicates that a user with an unverified email address attempted to authenticate in an environment where email verification is required. It includes a pending authentication token that should be used to complete the authentication.
+
+<CodeBlock
+  title="Email verification required error"
+  referenceId="email_verification_required_error"
+  file="email-verification-required-error"
+/>
+
+When this error occurs and the [email setting](/user-management/custom-emails) for email verification is enabled, WorkOS will automatically send a one-time email verification code to the user’s email address and issue a pending authentication token. If the email setting is not enabled, [retrieve the email verification code](/reference/user-management/email-verification/get) to send the email verification email yourself. To complete the authentication process, use the pending authentication token from the error and the one-time code the user received to [authenticate](/reference/user-management/authentication) them and to verify their email address.
+
+The same applies when a user attempts to authenticate with OAuth or SSO, but there was already an account with a matching unverified email address.

package/.docs/organized/docs/reference/user-management/authentication-errors/index.mdx

@@ -0,0 +1,20 @@
+---
+descriptions:
+  authentication_errors:
+    code: A string constant that distinguishes the error type.
+    message: A human-readable message describing the error.
+    pending_authentication_token: >
+      A token that should be used to complete the authentication with a
+      corresponding method after this error occurs.
+    email: The email of the authenticating user.
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/user-management/authentication-errors/index.mdx
+---
+
+---
+
+# Authentication errors
+
+Integrating the authentication API directly requires handling error responses for email verification, MFA challenges, identity linking, and organization selection. One or more of these responses may be returned for an authentication attempt with any authentication method.
+
+Hosted AuthKit handles authentication errors for you and may be a good choice if you prefer a simpler integration.

package/.docs/organized/docs/reference/user-management/authentication-errors/mfa-challenge-error.mdx

@@ -0,0 +1,44 @@
+---
+descriptions:
+  authentication_errors:
+    authentication_factors: |
+      IDs and types of the [factors](/reference/mfa) the user is enrolled in.
+reference:
+  json:
+    - key: mfa_challenge_error
+      id: mfa_challenge_error
+      url: /reference/user-management/authentication-errors/mfa-challenge-error
+      title: mfa_challenge
+      properties:
+        - key: code
+          type: '"mfa_challenge"'
+          description: (authentication_errors.code)
+        - key: message
+          type: string
+          description: (authentication_errors.message)
+        - key: pending_authentication_token
+          type: string
+          description: (authentication_errors.pending_authentication_token)
+        - key: authentication_factors
+          type: array
+          description: (authentication_errors.authentication_factors)
+        - key: user
+          type: user
+          description: (user.self)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/user-management/authentication-errors/mfa-challenge-error.mdx
+---
+
+## MFA challenge error
+
+This error indicates that a user enrolled into MFA attempted to authenticate in an environment where MFA is required. It includes a pending authentication token and a list of factors that the user is enrolled in that should be used to complete the authentication.
+
+<CodeBlock
+  title="MFA challenge error"
+  referenceId="mfa_challenge_error"
+  file="mfa-challenge-error"
+/>
+
+When this error occurs, you’ll need to present an MFA challenge UI to the user and authenticate them with their [TOTP code](/reference/user-management/authentication/totp), the pending authentication token from this error, and a [challenge](/reference/mfa/challenge-factor) that corresponds to one of the authentication factors.
+
+MFA can be enabled via the [Authentication page](https://dashboard.workos.com/authentication) in the WorkOS dashboard.

package/.docs/organized/docs/reference/user-management/authentication-errors/mfa-enrollment-error.mdx

@@ -0,0 +1,37 @@
+---
+reference:
+  json:
+    - key: mfa_enrollment_error
+      id: mfa_enrollment_error
+      url: /reference/user-management/authentication-errors/mfa-enrollment-error
+      title: mfa_enrollment
+      properties:
+        - key: code
+          type: '"mfa_enrollment"'
+          description: (authentication_errors.code)
+        - key: message
+          type: string
+          description: (authentication_errors.message)
+        - key: pending_authentication_token
+          type: string
+          description: (authentication_errors.pending_authentication_token)
+        - key: user
+          type: user
+          description: (user.self)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/user-management/authentication-errors/mfa-enrollment-error.mdx
+---
+
+## MFA enrollment error
+
+This error indicates that a user who is not enrolled into MFA attempted to authenticate in an environment where MFA is required. It includes a pending authentication token that should be used to authenticate the user once they enroll into MFA.
+
+<CodeBlock
+  title="MFA enrollment error"
+  referenceId="mfa_enrollment_error"
+  file="mfa-enrollment-error"
+/>
+
+When this error occurs, you’ll need to present an [MFA enrollment](/reference/user-management/mfa/enroll-auth-factor) UI to the user. Once the user has enrolled, present an MFA challenge UI to the user and authenticate them with their [TOTP code](/reference/user-management/authentication/totp) and the pending authentication token from this error.
+
+MFA can be enabled via the [Authentication page](https://dashboard.workos.com/authentication) in the WorkOS dashboard.

package/.docs/organized/docs/reference/user-management/authentication-errors/organization-authentication-required-error.mdx

@@ -0,0 +1,68 @@
+---
+descriptions:
+  authentication_errors:
+    sso_connection_ids: >
+      A list of SSO [connection](/reference/sso/connection) IDs that the user
+      can authenticate with.
+    apple_oauth: Whether or not Sign in with Apple is enabled for the organization.
+    github_oauth: Whether or not GitHub OAuth is enabled for the organization.
+    google_oauth: Whether or not Google OAuth is enabled for the organization.
+    microsoft_oauth: Whether or not Microsoft OAuth is enabled for the organization.
+    password: Whether or not password authentication is enabled for the organization.
+    magic_auth: Whether or not Magic Auth is enabled for the organization.
+reference:
+  json:
+    - key: organization_authentication_required_error
+      id: organization_authentication_required_error
+      url: >-
+        /reference/user-management/authentication-errors/organization-authentication-required-error
+      title: organization_authentication_methods_required
+      properties:
+        - key: error
+          type: '"organization_authentication_methods_required"'
+          description: (authentication_errors.code)
+        - key: error_description
+          type: string
+          description: (authentication_errors.message)
+        - key: email
+          type: string
+          description: (authentication_errors.email)
+        - key: sso_connection_ids
+          type: array
+          description: (authentication_errors.connection_ids)
+        - key: auth_methods
+          type: object
+          properties:
+            - key: apple_oauth
+              type: boolean
+              description: (authentication_errors.apple_oauth)
+            - key: github_oauth
+              type: boolean
+              description: (authentication_errors.github_oauth)
+            - key: google_oauth
+              type: boolean
+              description: (authentication_errors.google_oauth)
+            - key: magic_auth
+              type: boolean
+              description: (authentication_errors.magic_auth)
+            - key: microsoft_oauth
+              type: boolean
+              description: (authentication_errors.microsoft_oauth)
+            - key: password
+              type: boolean
+              description: (authentication_errors.password)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/user-management/authentication-errors/organization-authentication-required-error.mdx
+---
+
+## Organization authentication required error
+
+This error indicates that a user attempted to authenticate with an authentication method that is not allowed by the organization that has a [domain policy](/user-management/organization-policies) managing this user. It includes all the possible methods the user can use to authenticate.
+
+<CodeBlock
+  title="Organization authentication required error"
+  referenceId="organization_authentication_required_error"
+  file="organization-authentication-required-error"
+/>
+
+When this error occurs, you’ll need to present the user with these options so they can choose which method to continue authentication.

package/.docs/organized/docs/reference/user-management/authentication-errors/organization-selection-error.mdx

@@ -0,0 +1,44 @@
+---
+descriptions:
+  authentication_errors:
+    organizations: >
+      IDs and names of the [organizations](/reference/organization) the user is
+      a member of.
+reference:
+  json:
+    - key: organization_selection_required_error
+      id: organization_selection_required_error
+      url: >-
+        /reference/user-management/authentication-errors/organization-selection-error
+      title: organization_selection_required
+      properties:
+        - key: code
+          type: '"organization_selection_required"'
+          description: (authentication_errors.code)
+        - key: message
+          type: string
+          description: (authentication_errors.message)
+        - key: pending_authentication_token
+          type: string
+          description: (authentication_errors.pending_authentication_token)
+        - key: user
+          type: user
+          description: (user.self)
+        - key: organizations
+          type: array
+          description: (authentication_errors.organizations)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/user-management/authentication-errors/organization-selection-error.mdx
+---
+
+## Organization selection required error
+
+This error indicates that the user is a member of multiple organizations and must select which organization to sign in to. It includes a list of organizations the user is a member of and a pending authentication token that should be used to complete the authentication.
+
+<CodeBlock
+  title="Organization selection required error"
+  referenceId="organization_selection_required_error"
+  file="organization-selection-error"
+/>
+
+When this error occurs, you’ll need to display the list of organizations that the user is a member of and authenticate them with the [selected organization](/reference/user-management/authentication/organization-selection) using the pending authentication token from the error.

package/.docs/organized/docs/reference/user-management/authentication-errors/sso-required-error.mdx

@@ -0,0 +1,51 @@
+---
+descriptions:
+  authentication_errors:
+    connection_ids: >
+      A list of SSO [connection](/reference/sso/connection) IDs that the user is
+      required to authenticate with. One of these connections must be used.
+    optional_pending_authentication_token: >
+      A token that should be used to complete the authentication with the
+      `authorization_code` grant type after this error occurs.
+
+
+      This may be `null`, which indicates that no pending authentication token
+      needs to be passed to the authenticate call.
+reference:
+  json:
+    - key: sso_required_error
+      id: sso_required_error
+      url: /reference/user-management/authentication-errors/sso-required-error
+      title: sso_required
+      properties:
+        - key: error
+          type: '"sso_required"'
+          description: (authentication_errors.code)
+        - key: error_description
+          type: string
+          description: (authentication_errors.message)
+        - key: email
+          type: string
+          description: (authentication_errors.email)
+        - key: connection_ids
+          type: array
+          description: (authentication_errors.connection_ids)
+        - key: pending_authentication_token
+          type: string
+          optional: true
+          description: (authentication_errors.optional_pending_authentication_token)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/user-management/authentication-errors/sso-required-error.mdx
+---
+
+## SSO required error
+
+This error indicates that a user attempted to authenticate into an organization that requires SSO using a different authentication method. It includes a list of SSO connections that may be used to complete the authentication.
+
+<CodeBlock
+  title="SSO required error"
+  referenceId="sso_required_error"
+  file="sso-required-error"
+/>
+
+When this error occurs, you’ll need to use one of the SSO connections from the error to [get the authorization URL](/reference/user-management/authentication/get-authorization-url) and redirect the user to that URL to complete the authentication with the organization’s identity provider.