@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/reference/user-management/authentication/get-authorization-url/index.mdx

@@ -0,0 +1,425 @@
+---
+descriptions:
+  user_management_get_authorization_url:
+    response_type: >
+      The only valid option for the response type parameter is `"code"`.
+
+
+      The `"code"` parameter value initiates an [authorization code grant
+      type](https://tools.ietf.org/html/rfc6749#section-4.1). This grant type
+      allows you to exchange an authorization code for an access token during
+      the redirect that takes place after a user has authenticated with an
+      identity provider.
+    redirect_uri: >-
+      Where to redirect the user after they complete the authentication process.
+      You must use one of the redirect URIs configured via the
+      [Redirects](https://dashboard.workos.com/redirects) page on the dashboard.
+    connection_id: >
+      Used to initiate SSO for a connection. The value should be a WorkOS
+      connection ID.
+
+
+      You can persist the WorkOS connection ID with application user or team
+      identifiers. WorkOS will use the connection indicated by the connection
+      parameter to direct the user to the corresponding IdP for authentication.
+    organization_id: >
+      Used to initiate SSO for an organization. The value should be a WorkOS
+      organization ID.
+
+
+      You can persist the WorkOS organization ID with application user or team
+      identifiers. WorkOS will use the organization ID to determine the
+      appropriate connection and the IdP to direct the user to for
+      authentication.
+
+
+      If this parameter is passed when `provider` is also set to `authkit`, then
+      the organization will be automatically selected during the authentication
+      flow.
+    provider: >
+      Used to initiate authentication with AuthKit, Google OAuth, Microsoft
+      OAuth, GitHub OAuth, or Sign in with Apple.
+    state: >
+      An optional parameter that can be used to encode arbitrary information to
+      help restore application state between redirects. If included, the
+      redirect URI received from WorkOS will contain the exact state value that
+      was passed.
+    login_hint: >
+      Can be used to pre-fill the username/email address field of the IdP
+      sign-in page for the user, if you know their username ahead of time.
+
+
+      Currently, this parameter is supported for OAuth, Authkit, OpenID Connect,
+      Okta, and Entra ID connections.
+    domain_hint: >
+      Can be used to pre-fill the domain field when initiating authentication
+      with Microsoft OAuth or with a Google SAML connection type.
+    url: An OAuth 2.0 authorization URL.
+    screen_hint: >
+      Specify which AuthKit screen users should land on upon redirection (Only
+      applicable when provider is 'authkit').
+    code_challenge: Code challenge is derived from the code verifier used for the PKCE flow.
+    code_challenge_method: >
+      The only valid PKCE code challenge method is `"S256"`.
+
+
+      This parameter is required when specifying a `code_challenge` for the PKCE
+      flow.
+reference:
+  curl:
+    - url: /reference/user-management/authentication/get-authorization-url
+      key: user_management_get_authorization_url
+      id: user_management_get_authorization_url
+      title: /user_management/authorize
+      type: GET
+      properties:
+        - key: response_type
+          type: '"code"'
+          description: (user_management_get_authorization_url.response_type)
+        - key: client_id
+          type: string
+          description: (client_id)
+        - key: code_challenge
+          optional: true
+          type: string
+          description: (user_management_get_authorization_url.code_challenge)
+        - key: code_challenge_method
+          optional: true
+          type: '"S256"'
+          description: (user_management_get_authorization_url.code_challenge_method)
+        - key: redirect_uri
+          type: string
+          description: (user_management_get_authorization_url.redirect_uri)
+        - key: connection_id
+          optional: true
+          type: string
+          description: (user_management_get_authorization_url.connection_id)
+        - key: organization_id
+          optional: true
+          type: string
+          description: (user_management_get_authorization_url.organization_id)
+        - key: provider
+          optional: true
+          type: >-
+            "authkit" | "AppleOAuth" | "GitHubOAuth" | "GoogleOAuth" |
+            "MicrosoftOAuth"
+          description: (user_management_get_authorization_url.provider)
+        - key: state
+          optional: true
+          type: string
+          description: (user_management_get_authorization_url.state)
+        - key: login_hint
+          optional: true
+          type: string
+          description: (user_management_get_authorization_url.login_hint)
+        - key: domain_hint
+          optional: true
+          type: string
+          description: (user_management_get_authorization_url.domain_hint)
+        - key: screen_hint
+          optional: true
+          type: '"sign-up" | "sign-in"'
+          description: (user_management_get_authorization_url.screen_hint)
+      returns:
+        - key: url
+          type: string
+          description: (user_management_get_authorization_url.url)
+  js:
+    - url: /reference/user-management/authentication/get-authorization-url
+      key: getAuthorizationUrl
+      patternBefore: userManagement.
+      id: user_management_get_authorization_url
+      title: userManagement.getAuthorizationUrl()
+      parameters:
+        - key: options
+          type: object
+          unwrap: true
+          properties:
+            - key: redirectUri
+              type: string
+              description: (user_management_get_authorization_url.redirect_uri)
+            - key: clientId
+              type: string
+              description: (client_id)
+            - key: codeChallenge
+              optional: true
+              type: string
+              description: (user_management_get_authorization_url.code_challenge)
+            - key: codeChallengeMethod
+              optional: true
+              type: '"S256"'
+              description: (user_management_get_authorization_url.code_challenge_method)
+            - key: connectionId
+              optional: true
+              type: string
+              description: (user_management_get_authorization_url.connection_id)
+            - key: organizationId
+              optional: true
+              type: string
+              description: (user_management_get_authorization_url.organization_id)
+            - key: provider
+              optional: true
+              type: >-
+                "authkit" | "AppleOAuth" | "GitHubOAuth" | "GoogleOAuth" |
+                "MicrosoftOAuth"
+              description: (user_management_get_authorization_url.provider)
+            - key: state
+              optional: true
+              type: string
+              description: (user_management_get_authorization_url.state)
+            - key: loginHint
+              optional: true
+              type: string
+              description: (user_management_get_authorization_url.login_hint)
+            - key: domainHint
+              optional: true
+              type: string
+              description: (user_management_get_authorization_url.domain_hint)
+            - key: screenHint
+              optional: true
+              type: '"sign-up" | "sign-in"'
+              description: (user_management_get_authorization_url.screen_hint)
+      returns:
+        - key: url
+          type: string
+          description: (user_management_get_authorization_url.url)
+  python:
+    - url: /reference/user-management/authentication/get-authorization-url
+      key: get_authorization_url
+      patternBefore: user_management.
+      id: user_management_get_authorization_url
+      title: user_management.get_authorization_url()
+      parameters:
+        - key: redirect_uri
+          type: str
+          description: (user_management_get_authorization_url.redirect_uri)
+        - key: connection_id
+          optional: true
+          type: str
+          description: (user_management_get_authorization_url.connection_id)
+        - key: organization_id
+          optional: true
+          type: str
+          description: (user_management_get_authorization_url.organization_id)
+        - key: provider
+          optional: true
+          type: UserManagementProviderType
+          description: (user_management_get_authorization_url.provider)
+        - key: state
+          optional: true
+          type: str
+          description: (user_management_get_authorization_url.state)
+        - key: login_hint
+          optional: true
+          type: str
+          description: (user_management_get_authorization_url.login_hint)
+        - key: domain_hint
+          optional: true
+          type: str
+          description: (user_management_get_authorization_url.domain_hint)
+      returns:
+        - key: url
+          type: str
+          description: (user_management_get_authorization_url.url)
+  go:
+    - url: /reference/user-management/authentication/get-authorization-url
+      key: GetAuthorizationURL
+      patternBefore: usermanagement.
+      id: user_management_get_authorization_url
+      title: usermanagement.GetAuthorizationURL()
+      parameters:
+        - (ctx)
+        - key: opts
+          type: usermanagement.GetAuthorizationURLOpts
+          unwrap: true
+          properties:
+            - key: RedirectURI
+              type: string
+              description: (user_management_get_authorization_url.redirect_uri)
+            - key: ClientID
+              type: string
+              description: (client_id)
+            - key: CodeChallenge
+              optional: true
+              type: string
+              description: (user_management_get_authorization_url.code_challenge)
+            - key: CodeChallengeMethod
+              optional: true
+              type: '"S256"'
+              description: (user_management_get_authorization_url.code_challenge_method)
+            - key: ConnectionID
+              optional: true
+              type: string
+              description: (user_management_get_authorization_url.connection_id)
+            - key: OrganizationID
+              optional: true
+              type: string
+              description: (user_management_get_authorization_url.organization_id)
+            - key: Provider
+              optional: true
+              type: string
+              description: (user_management_get_authorization_url.provider)
+            - key: State
+              optional: true
+              type: string
+              description: (user_management_get_authorization_url.state)
+            - key: LoginHint
+              optional: true
+              type: string
+              description: (user_management_get_authorization_url.login_hint)
+            - key: DomainHint
+              optional: true
+              type: string
+              description: (user_management_get_authorization_url.domain_hint)
+            - key: ScreenHint
+              optional: true
+              type: ScreenHint
+              description: (user_management_get_authorization_url.screen_hint)
+      returns:
+        - key: url
+          type: string
+          description: (user_management_get_authorization_url.url)
+        - (err)
+  php:
+    - url: /reference/user-management/authentication/get-authorization-url
+      key: getAuthorizationUrl
+      id: user_management_get_authorization_url
+      patternBefore: userManagement->
+      title: $userManagement->getAuthorizationUrl()
+      parameters:
+        - key: redirectUri
+          type: str
+          description: (user_management_get_authorization_url.redirect_uri)
+        - key: connectionId
+          optional: true
+          type: str
+          description: (user_management_get_authorization_url.connection_id)
+        - key: organizationId
+          optional: true
+          type: str
+          description: (user_management_get_authorization_url.organization_id)
+        - key: provider
+          optional: true
+          type: >-
+            "authkit" | "AppleOAuth" | "GitHubOAuth" | "GoogleOAuth" |
+            "MicrosoftOAuth"
+          description: (user_management_get_authorization_url.provider)
+        - key: state
+          optional: true
+          type: str
+          description: (user_management_get_authorization_url.state)
+        - key: loginHint
+          optional: true
+          type: str
+          description: (user_management_get_authorization_url.login_hint)
+        - key: domainHint
+          optional: true
+          type: str
+          description: (user_management_get_authorization_url.domain_hint)
+      returns:
+        - key: url
+          type: string
+          description: (user_management_get_authorization_url.url)
+  ruby:
+    - url: /reference/user-management/authentication/get-authorization-url
+      key: authorization_url
+      id: user_management_get_authorization_url
+      title: UserManagement.authorization_url()
+      parameters:
+        - key: redirect_uri
+          type: String
+          description: (user_management_get_authorization_url.redirect_uri)
+        - key: client_id
+          type: String
+          description: (client_id)
+        - key: domain_hint
+          optional: true
+          type: String
+          description: (user_management_get_authorization_url.domain_hint)
+        - key: login_hint
+          optional: true
+          type: String
+          description: (user_management_get_authorization_url.login_hint)
+        - key: provider
+          optional: true
+          type: >-
+            "authkit" | "AppleOAuth" | "GitHubOAuth" | "GoogleOAuth" |
+            "MicrosoftOAuth"
+          description: (user_management_get_authorization_url.provider)
+        - key: connection_id
+          optional: true
+          type: String
+          description: (user_management_get_authorization_url.connection_id)
+        - key: organization_id
+          optional: true
+          type: String
+          description: (user_management_get_authorization_url.organization_id)
+        - key: state
+          optional: true
+          type: String
+          description: (user_management_get_authorization_url.state)
+      returns:
+        - key: url
+          type: String
+          description: (user_management_get_authorization_url.url)
+  java:
+    - url: /reference/user-management/authentication/get-authorization-url
+      key: authorization_url
+      id: user_management_get_authorization_url
+      title: userManagement.getAuthorizationUrl()
+      parameters:
+        - key: clientId
+          type: String
+          description: (client_id)
+        - key: redirectUri
+          type: String
+          description: (user_management_get_authorization_url.redirect_uri)
+      returns:
+        - key: response
+          type: AuthorizationUrlOptionsBuilder
+          unwrap: true
+          properties:
+            - key: connectionId
+              optional: true
+              type: String
+              description: (user_management_get_authorization_url.connection_id)
+            - key: domainHint
+              optional: true
+              type: String
+              description: (user_management_get_authorization_url.domain_hint)
+            - key: loginHint
+              optional: true
+              type: String
+              description: (user_management_get_authorization_url.login_hint)
+            - key: screenHint
+              optional: true
+              type: String
+              description: (user_management_get_authorization_url.login_hint)
+            - key: organizationId
+              optional: true
+              type: String
+              description: (user_management_get_authorization_url.organization_id)
+            - key: provider
+              optional: true
+              type: UserManagementProviderEnumType
+              description: (user_management_get_authorization_url.provider)
+            - key: state
+              optional: true
+              type: String
+              description: (user_management_get_authorization_url.state)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/user-management/authentication/get-authorization-url/index.mdx
+---
+
+## Get an authorization URL
+
+Generates an OAuth 2.0 authorization URL to authenticate a user with AuthKit or SSO.
+
+<CodeBlock referenceId="user_management_get_authorization_url">
+  <CodeBlockTab title="Request" file="get-authorization-url-request" />
+  <CodeBlockTab title="Response" file="get-authorization-url-response" />
+</CodeBlock>
+
+If you are using AuthKit, set the provider parameter to `"authkit"`, which will generate an authorization URL for your AuthKit domain. AuthKit will take care of detecting the user’s authentication method, such as identifying whether they use Email + Password or Single Sign-On,and direct them to the corresponding login flow.
+
+Otherwise, to generate an authorization URL for a WorkOS SSO connection, you’ll have to specify the user’s connection, organization, or OAuth provider as a parameter. These connection selectors are mutually exclusive, and exactly one must be provided. The generated URL automatically directs the user to their identity provider. Once the user authenticates with their identity provider, WorkOS then issues a redirect to your redirect URI to complete the sign-in flow.

package/.docs/organized/docs/reference/user-management/authentication/get-authorization-url/pkce.mdx

@@ -0,0 +1,9 @@
+---
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/user-management/authentication/get-authorization-url/pkce.mdx
+---
+### PKCE
+
+The [Proof Key for Code Exchange](https://datatracker.ietf.org/doc/html/rfc7636) (PKCE) flow is an extension to the OAuth 2.0 Authorization Code flow. It enables public clients, like native apps or single-page apps, to perform the authorization code flow securely. If you are developing a client that makes API calls in public, you’ll need to use this flow.
+
+In this flow, your client generates a code verifier which is a high-entropy cryptographic random string. A code challenge is derived by hashing the code verifier. Instead of using a client secret, provide the code challenge when [getting the authorization URL](/reference/user-management/authentication/get-authorization-url) and the code verifier when [authenticating a User](/reference/user-management/authentication/code).

package/.docs/organized/docs/reference/user-management/authentication/get-authorization-url/redirect-uri.mdx

@@ -0,0 +1,23 @@
+---
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/user-management/authentication/get-authorization-url/redirect-uri.mdx
+---
+### Redirect URI
+
+In the [OAuth 2.0](/glossary/oauth-2-0) protocol, a redirect URI is the location that the user is redirected to once they have successfully authenticated with their identity provider.
+
+When redirecting the user, WorkOS will generate an authorization code and pass it to your redirect URI as a `code` query parameter, your app will use this code to [authenticate the user](/reference/user-management/authentication/code). Additionally, WorkOS can pass a `state` parameter back to your application that you may use to encode arbitrary information to restore your application state between the redirects.
+
+```url title="Redirect URI with query parameters"
+https://your-app.com/callback?code=01E2RJ4C05B52KKZ8FSRDAP23J&state=dj1kUXc0dzlXZ1hjUQ==
+```
+
+You can use `state` to encode parameters like originating URL and query parameters. This is useful in a flow where unauthenticated users are automatically redirected to a login page. After successful sign in, users will be routed to your redirect URI callback route. From there you can extract the originating URL from `state` and redirect the user to their intended destination.
+
+You’ll need to configure the allowed redirect URIs for your application via the [Redirects](https://dashboard.workos.com/redirects) page in the dashboard. Without a valid redirect URI, your users will be unable to sign in. Make sure that the redirect URI you use as a parameter to get the authorization URL matches one of the redirect URIs you have configured in the dashboard.
+
+Redirect URIs follow stricter requirements in production environments:
+
+- `HTTPS` protocol is required in production environments
+- `HTTP` and `localhost` are allowed in staging environments
+- Wildcard characters are not allowed in production environments

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

@@ -0,0 +1,66 @@
+---
+descriptions:
+  authentication:
+    grant_type: >-
+      A string constant that distinguishes the method by which your application
+      will receive an access token.
+    ip_address: >
+      The IP address of the request from the user who is attempting to
+      authenticate.
+
+
+      Refer to your web framework or server documentation for the correct way to
+      obtain the user’s actual IP
+
+      address. If your application receives requests from a reverse proxy, you
+      may need to retrieve this from
+
+      a special header like `X-Forward-For`.
+    user_agent: >
+      The user agent of the request from the user who is attempting to
+      authenticate. This should be the value
+
+      of the `User-Agent` header.
+    invitation_token: >
+      The token of an [invitation](/reference/user-management/invitation). The
+      invitation should be in the pending state.
+
+
+      When a valid invitation token is specified, the user is able to sign up
+      even if it is disabled in the environment. Additionally, if the invitation
+      was for a specific organization, attaching the token to a user's
+      authenticate call automatically provisions their membership to the
+      organization.
+    organization_id: >
+      The [organization](/reference/organization) the user selected to sign in
+      to.
+
+
+      If the user is a member of multiple organizations, this is the
+      organization the user
+      [selected](/reference/user-management/authentication/organization-selection)
+      as part of the authentication flow. If the user is a member of only one
+      organization, this is that organization. If the user is not a member of
+      any organizations, this is `null`.
+    pending_authentication_token: >-
+      The authentication token returned from a failed authentication attempt due
+      to the corresponding error.
+    authentication_method: The authentication method used to initiate the session.
+    access_token: |
+      A JWT containing information about the current session.
+    seal_session: Whether or not to include the sealed session data in the return value.
+    cookie_password_seal: >-
+      Password used to the seal the session cookie. Can alternatively be
+      specified as the `WORKOS_COOKIE_PASSWORD` environment variable.
+    sealed_session: >-
+      The sealed session data to be set as a cookie in the user's browser. Only
+      returned if the seal session parameter was true.
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/user-management/authentication/index.mdx
+---
+
+---
+
+# Authentication
+
+Authenticate a user with a specified authentication method.