@workos/mcp-docs-server 0.1.0

package/.docs/organized/docs/reference/sso/get-authorization-url/error-codes.mdx

@@ -0,0 +1,28 @@
+---
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/sso/get-authorization-url/error-codes.mdx
+---
+### Error codes
+
+If there is an issue generating an authorization URL, the API will return the original redirect URI with `error` and `error_description` query parameters. If provided, the `state` value will also be included.
+
+```url title="Redirect URI with an error code"
+https://your-app.com/callback?error=organization_invalid&error_description=No%20connection%20associated%20with%20organization&state=123456789
+```
+
+Possible error codes and the corresponding descriptions are listed below.
+
+| Error code                                 | Description                                                                                                                                                                                                                                                                                                                        |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `access_denied`                            | The user denied an OAuth authorization request at the identity provider.                                                                                                                                                                                                                                                           |
+| `ambiguous_connection_selector`            | A connection could not be uniquely identified using the provided connection selector (e.g., organization). This can occur when there are multiple SSO connections under the same organization. If you need multiple SSO connections for an organization, use the connection parameter to identify which connection to use for SSO. |
+| `connection_domain_invalid`                | There is no connection for the provided domain.                                                                                                                                                                                                                                                                                    |
+| `connection_invalid`                       | There is no connection for the provided ID.                                                                                                                                                                                                                                                                                        |
+| `connection_strategy_invalid`              | The provider has multiple strategies associated per environment.                                                                                                                                                                                                                                                                   |
+| `connection_unlinked`                      | The connection associated with the request is unlinked.                                                                                                                                                                                                                                                                            |
+| `domain_connection_selector_not_allowed`   | This is a legacy error code that only applies if using the deprecated “domain” query parameter which is no longer valid for this endpoint. Use the “organization” or “connection” query parameters to target a connection instead.                                                                                                 |
+| `invalid_connection_selector`              | A valid connection selector query parameter must be provided in order to correctly determine the proper connection to return an authorization URL for. Valid connection selectors are either `connection`, `organization`, or `provider`.                                                                                          |
+| `organization_invalid`                     | There is no organization matching the provided ID.                                                                                                                                                                                                                                                                                 |
+| `oauth_failed`                             | An OAuth authorization request failed for a user.                                                                                                                                                                                                                                                                                  |
+| `profile_not_allowed_outside_organization` | A profile was received that has an `email` that is outside the [organization’s domain](/reference/organization-domain) and the organization does not allow this. To resolve this, add the missing domain to the organization's Domains. You can read about other options in the [SSO Domains guide](/sso/domains).                 |
+| `server_error`                             | The SSO authentication failed for the user. More detailed errors and steps to resolve are available in the [Sessions tab](/dashboard/saml-sessions/sessions-tab) on the connection page in the WorkOS Dashboard.                                                                                                                   |

package/.docs/organized/docs/reference/sso/get-authorization-url/index.mdx

@@ -0,0 +1,434 @@
+---
+descriptions:
+  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: >
+      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: >
+      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.
+    provider: >
+      Used to initiate OAuth authentication with Google, Microsoft, GitHub, or
+      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` 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, 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.
+reference:
+  curl:
+    - url: /reference/sso/get-authorization-url
+      key: get_authorization_url
+      id: get_authorization_url
+      title: /sso/authorize
+      type: GET
+      properties:
+        - key: response_type
+          type: '"code"'
+          description: (get_authorization_url.response_type)
+        - key: client_id
+          type: string
+          description: (client_id)
+        - key: redirect_uri
+          type: string
+          description: (get_authorization_url.redirect_uri)
+        - key: connection
+          optional: true
+          type: string
+          description: (get_authorization_url.connection)
+        - key: organization
+          optional: true
+          type: string
+          description: (get_authorization_url.organization)
+        - key: provider
+          optional: true
+          type: '"AppleOAuth" | "GitHubOAuth" | "GoogleOAuth" | "MicrosoftOAuth"'
+          description: (get_authorization_url.provider)
+        - key: state
+          optional: true
+          type: string
+          description: (get_authorization_url.state)
+        - key: login_hint
+          optional: true
+          type: string
+          description: (get_authorization_url.login_hint)
+        - key: domain_hint
+          optional: true
+          type: string
+          description: (get_authorization_url.domain_hint)
+      returns:
+        - key: url
+          type: string
+          description: (get_authorization_url.url)
+  dotnet:
+    - url: /reference/sso/get-authorization-url
+      key: GetAuthorizationURL
+      patternBefore: ssoService.
+      id: get_authorization_url
+      title: ssoService.GetAuthorizationURL()
+      parameters:
+        - key: options
+          type: GetAuthorizationURLOptions
+          expanded: true
+          properties:
+            - key: ResponseType
+              type: '"code"'
+              description: (get_authorization_url.response_type)
+            - key: ClientId
+              type: string
+              description: (client_id)
+            - key: RedirectURI
+              type: string
+              description: (get_authorization_url.redirect_uri)
+            - key: Connection
+              optional: true
+              type: string
+              description: (get_authorization_url.connection)
+            - key: Organization
+              optional: true
+              type: string
+              description: (get_authorization_url.organization)
+            - key: Provider
+              optional: true
+              type: ProviderType
+              description: (get_authorization_url.provider)
+            - key: State
+              optional: true
+              type: string
+              description: (get_authorization_url.state)
+            - key: LoginHint
+              optional: true
+              type: string
+              description: (get_authorization_url.login_hint)
+            - key: DomainHint
+              optional: true
+              type: string
+              description: (get_authorization_url.domain_hint)
+      returns:
+        - key: url
+          type: string
+          description: (get_authorization_url.url)
+  java:
+    - url: /reference/sso/get-authorization-url
+      key: getAuthorizationUrl
+      patternBefore: sso.
+      id: get_authorization_url
+      title: sso.getAuthorizationUrl()
+      parameters:
+        - key: clientId
+          type: String
+        - key: redirectUri
+          type: String
+      returns:
+        - key: builder
+          type: AuthorizationUrlOptionsBuilder
+          expanded: true
+          properties:
+            - key: 'connection(value: String)'
+              description: (get_authorization_url.connection)
+            - key: 'organization(value: String)'
+              description: (get_authorization_url.organization)
+            - key: 'provider(value: String)'
+              description: (get_authorization_url.provider)
+            - key: 'state(value: String)'
+              description: (get_authorization_url.state)
+            - key: 'domainHint(value: String)'
+              description: (get_authorization_url.domain_hint)
+            - key: 'loginHint(value: String)'
+              description: (get_authorization_url.login_hint)
+            - key: build()
+              type: String
+              description: Performs the request and returns an OAuth 2.0 authorization URL.
+  ruby:
+    - url: /reference/sso/get-authorization-url
+      key: authorization_url
+      patternBefore: SSO.
+      id: get_authorization_url
+      title: SSO.authorization_url()
+      parameters:
+        - key: redirect_uri
+          type: String
+          description: (get_authorization_url.redirect_uri)
+        - key: client_id
+          type: String
+          description: (client_id)
+        - key: connection
+          optional: true
+          type: String
+          description: (get_authorization_url.connection)
+        - key: organization
+          optional: true
+          type: String
+          description: (get_authorization_url.organization)
+        - key: provider
+          optional: true
+          type: '"AppleOAuth" | "GitHubOAuth" | "GoogleOAuth" | "MicrosoftOAuth"'
+          description: (get_authorization_url.provider)
+        - key: state
+          optional: true
+          type: String
+          description: (get_authorization_url.state)
+        - key: login_hint
+          optional: true
+          type: String
+          description: (get_authorization_url.login_hint)
+        - key: domain_hint
+          optional: true
+          type: String
+          description: (get_authorization_url.domain_hint)
+      returns:
+        - key: url
+          type: String
+          description: (get_authorization_url.url)
+  php:
+    - url: /reference/sso/get-authorization-url
+      key: getAuthorizationUrl
+      patternBefore: sso->
+      id: get_authorization_url
+      title: $sso->getAuthorizationUrl()
+      parameters:
+        - key: redirectUri
+          type: string
+          description: (get_authorization_url.redirect_uri)
+        - key: connection
+          optional: true
+          type: string
+          description: (get_authorization_url.connection)
+        - key: organization
+          optional: true
+          type: string
+          description: (get_authorization_url.organization)
+        - key: provider
+          optional: true
+          type: '"AppleOAuth" | "GitHubOAuth" | "GoogleOAuth" | "MicrosoftOAuth"'
+          description: (get_authorization_url.provider)
+        - key: state
+          optional: true
+          type: string
+          description: (get_authorization_url.state)
+        - key: loginHint
+          optional: true
+          type: string
+          description: (get_authorization_url.login_hint)
+        - key: domainHint
+          optional: true
+          type: string
+          description: (get_authorization_url.domain_hint)
+      returns:
+        - key: url
+          type: string
+          description: (get_authorization_url.url)
+  python:
+    - url: /reference/sso/get-authorization-url
+      key: get_authorization_url
+      patternBefore: sso.
+      id: get_authorization_url
+      title: sso.get_authorization_url()
+      parameters:
+        - key: redirect_uri
+          type: str
+          description: (get_authorization_url.redirect_uri)
+        - key: connection_id
+          optional: true
+          type: str
+          description: (get_authorization_url.connection)
+        - key: organization_id
+          optional: true
+          type: str
+          description: (get_authorization_url.organization)
+        - key: provider
+          optional: true
+          type: SsoProviderType
+          description: (get_authorization_url.provider)
+        - key: state
+          optional: true
+          type: str
+          description: (get_authorization_url.state)
+        - key: login_hint
+          optional: true
+          type: str
+          description: (get_authorization_url.login_hint)
+        - key: domain_hint
+          optional: true
+          type: str
+          description: (get_authorization_url.domain_hint)
+      returns:
+        - key: url
+          type: str
+          description: (get_authorization_url.url)
+  js:
+    - url: /reference/sso/get-authorization-url
+      key: getAuthorizationUrl
+      patternBefore: sso.
+      id: get_authorization_url
+      title: sso.getAuthorizationUrl()
+      parameters:
+        - key: options
+          type: object
+          unwrap: true
+          properties:
+            - key: redirectUri
+              type: string
+              description: (get_authorization_url.redirect_uri)
+            - key: clientId
+              type: string
+              description: (client_id)
+            - key: connection
+              optional: true
+              type: string
+              description: (get_authorization_url.connection)
+            - key: organization
+              optional: true
+              type: string
+              description: (get_authorization_url.organization)
+            - key: provider
+              optional: true
+              type: '"AppleOAuth" | "GitHubOAuth" | "GoogleOAuth" | "MicrosoftOAuth"'
+              description: (get_authorization_url.provider)
+            - key: state
+              optional: true
+              type: string
+              description: (get_authorization_url.state)
+            - key: loginHint
+              optional: true
+              type: string
+              description: (get_authorization_url.login_hint)
+            - key: domainHint
+              optional: true
+              type: string
+              description: (get_authorization_url.domain_hint)
+      returns:
+        - key: url
+          type: string
+          description: (get_authorization_url.url)
+  go:
+    - url: /reference/sso/get-authorization-url
+      patternBefore: sso.
+      key: GetAuthorizationURL
+      id: get_authorization_url
+      title: sso.GetAuthorizationURL()
+      parameters:
+        - key: opts
+          type: sso.GetAuthorizationURLOpts
+          expanded: true
+          properties:
+            - key: RedirectURI
+              type: string
+              description: (get_authorization_url.redirect_uri)
+            - key: Connection
+              optional: true
+              type: string
+              description: (get_authorization_url.connection)
+            - key: Organization
+              optional: true
+              type: string
+              description: (get_authorization_url.organization)
+            - key: Provider
+              optional: true
+              type: sso.ConnectionType
+              description: (get_authorization_url.provider)
+            - key: State
+              optional: true
+              type: string
+              description: (get_authorization_url.state)
+            - key: LoginHint
+              optional: true
+              type: string
+              description: (get_authorization_url.login_hint)
+            - key: DomainHint
+              optional: true
+              type: string
+              description: (get_authorization_url.domain_hint)
+      returns:
+        - key: url
+          type: url.URL
+          description: (get_authorization_url.url)
+        - (err)
+    - url: /reference/sso/get-authorization-url
+      key: Login
+      id: go_login
+      title: sso.Login()
+      parameters:
+        - key: opts
+          type: sso.GetAuthorizationURLOpts
+          expanded: true
+          properties:
+            - key: RedirectURI
+              type: string
+              description: (get_authorization_url.redirect_uri)
+            - key: Connection
+              optional: true
+              type: string
+              description: (get_authorization_url.connection)
+            - key: Organization
+              optional: true
+              type: string
+              description: (get_authorization_url.organization)
+            - key: Provider
+              optional: true
+              type: sso.ConnectionType
+              description: (get_authorization_url.provider)
+            - key: State
+              optional: true
+              type: string
+              description: (get_authorization_url.state)
+            - key: LoginHint
+              optional: true
+              type: string
+              description: (get_authorization_url.login_hint)
+            - key: DomainHint
+              optional: true
+              type: string
+              description: (get_authorization_url.domain_hint)
+      returns:
+        - key: handler
+          type: http.Handler
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/sso/get-authorization-url/index.mdx
+---
+
+## Get an authorization URL
+
+Generates an OAuth 2.0 authorization URL to authenticate a user with SSO.
+
+<CodeBlock referenceId="get_authorization_url">
+  <CodeBlockTab title="Request" file="get-authorization-url-request" />
+  <CodeBlockTab title="Response" file="get-authorization-url-response" />
+</CodeBlock>
+
+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/sso/get-authorization-url/redirect-uri.mdx

@@ -0,0 +1,21 @@
+---
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/sso/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 [get the user’s profile](/reference/sso/profile/get-profile-and-token). 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’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/sso/index.mdx

@@ -0,0 +1,8 @@
+---
+originalPath: .tmp-workos-clone/packages/docs/content/reference/sso/index.mdx
+---
+# Single Sign-On
+
+The Single Sign-On API has been modeled to meet the [OAuth 2.0](/glossary/oauth-2-0) framework specification. As a result, authentication flows constructed using the Single Sign-On API replicate the OAuth 2.0 protocol flow.
+
+To automatically respond to changes in your SSO connections, use the [Connection events](/events/connection).

package/.docs/organized/docs/reference/sso/logout/authorize.mdx

@@ -0,0 +1,47 @@
+---
+featureFlag: single-logout-docs
+descriptions:
+  logout_authorize:
+    profile_id: |
+      The unique identifier of the WorkOS Profile to log out.
+  logout_authorize_response:
+    logout_url: >
+      The URL to redirect the user to in order to log out ([Logout
+      Redirect](/reference/sso/logout) endpoint ready to use)
+    logout_token: >
+      The logout token to be used in the [Logout
+      Redirect](/reference/sso/logout) endpoint.
+reference:
+  curl:
+    - url: /reference/sso/logout/authorize
+      key: logout_authorize
+      id: logout_authorize
+      title: /sso/logout/authorize
+      type: POST
+      parameters:
+        - key: profile_id
+          type: string
+          description: (logout_authorize.profile_id)
+      returns:
+        - key: anonymous
+          type: object
+          unwrap: true
+          properties:
+            - key: logout_url
+              type: string
+              description: (logout_authorize_response.logout_url)
+            - key: logout_token
+              type: string
+              description: (logout_authorize_response.logout_token)
+originalPath: .tmp-workos-clone/packages/docs/content/reference/sso/logout/authorize.mdx
+---
+
+## Logout Authorize
+
+You should call this endpoint from your server to generate a logout token which is required for
+the [Logout Redirect](/reference/sso/logout) endpoint.
+
+<CodeBlock referenceId="logout_authorize">
+  <CodeBlockTab title="Request" file="logout-authorize-request" />
+  <CodeBlockTab title="Response" file="logout-authorize-response" />
+</CodeBlock>

package/.docs/organized/docs/reference/sso/logout/index.mdx

@@ -0,0 +1,14 @@
+---
+featureFlag: single-logout-docs
+originalPath: .tmp-workos-clone/packages/docs/content/reference/sso/logout/index.mdx
+---
+
+## Logout
+
+The Logout endpoints enable the RP-initiated logout functionality for users in your application.
+Refer to [Single Logout](/sso/single-logout/idp-initiated-logout) section for more details on how to handle
+RP-initiated or IdP-initiated logout.
+
+> Please note that the Logout feature is only available for Custom Open ID connections that provide
+> specific logout features. These features include the presence of the `revocation_endpoint` and `end_session_endpoint`
+> in the discovery document.

package/.docs/organized/docs/reference/sso/logout/redirect.mdx

@@ -0,0 +1,32 @@
+---
+featureFlag: single-logout-docs
+descriptions:
+  logout:
+    token: >
+      The logout token returned from the [Logout
+      Authorize](/reference/sso/logout/authorize) endpoint.
+reference:
+  curl:
+    - url: /reference/sso/logout/redirect
+      key: logout_redirect
+      id: logout_redirect
+      title: /sso/logout
+      type: GET
+      parameters:
+        - key: token
+          type: string
+          description: (logout.token)
+originalPath: .tmp-workos-clone/packages/docs/content/reference/sso/logout/redirect.mdx
+---
+
+## Logout Redirect
+
+Logout allows to sign out a user from your application by triggering the identity provider sign out flow.
+This `GET` endpoint should be a redirection, since the identity provider user will be identified in the browser session.
+
+Before redirecting to this endpoint, you need to generate a short-lived logout token using the
+[Logout Authorize](/reference/sso/logout/authorize) endpoint.
+
+<CodeBlock referenceId="logout_redirect">
+  <CodeBlockTab title="Request" file="logout-request" />
+</CodeBlock>