> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connect.fastenhealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Component

> The stitch Web Component has multiple options that can be used to customize the look and feel of the component.

<Warning>
  You are looking at the documentation for an older version of the Stitch SDK

  [Stitch.js (v4)](/stitch/v4/) was recently released and is now the recommended version of the SDK.

  This version includes compatibility with additional runtime environments (Web, React Native, React etc), improved performance, and additional features.

  v4 is backwards compatible with v3 -- there are no breaking changes to the public API, but we have made significant improvements to the underlying codebase and architecture. If you are currently using v3, you can upgrade to v4 without making any changes to your code.

  Older versions of the SDK are in maintenance mode and will no longer receive updates (outside of security fixes).
  Please update your code to use the new version.
</Warning>

```html theme={null}
<fasten-stitch
    public-id="public_test_123456324234234"
    connect-mode="redirect"
    external-id="user_12345"
    external-state="unique-state-id"
>
</fasten-stitch>
```

<ParamField path="public-id" type="string" required>
  This must be your API public ID. You can find it in your [Fasten Connect Portal](https://portal.connect.fastenhealth.com).
</ParamField>

<ParamField path="connect-mode" type="string" default="redirect">
  Allows you to switch between `popup` and `redirect` modes. The default is `redirect`.

  When using `redirect` mode, the component will redirect the user to the authentication page.
  On successful authentication, the user will be redirected back to your `redirect_url` page (configured in the Fasten Connect Portal) with query string parameters.

  When using `popup` mode, the component will open a popup window to authenticate the user.
  On successful authentication, the popup window will close and the parent window will receive the authentication response via a `orgConnectionCallback` event.
</ParamField>

<ParamField path="popup-timeout" type="string" default="30">
  (Optional) When connect-mode = "popup", this can be used to specify the timeout for the popup, in minutes.
</ParamField>

<ParamField path="reconnect-org-connection-id" type="string">
  (Optional) Useful when the patient connection credentials are invalid (due to expiration or revocation). Providing this `reconnect-org-connection-id` allows Fasten to reauthenticate the Patient and store their new credentials.
</ParamField>

<ParamField path="request-id" type="string">
  An correlation id. This should be sent with any support ticket queries to the Fasten Connect support team.
</ParamField>

<ParamField path="external-id" type="string">
  (Optional) An Opaque identifier, used to identify the patient in your system. This value will be returned in the response.
</ParamField>

<ParamField path="external-state" type="string">
  (Optional) An Opaque identifier, used to uniquely identify in connection request. This value should be unique for each request. This value will be returned in the response.
</ParamField>

# Response

The response content is the same for both `redirect` and `popup` modes. However the response delivery mechanism is different.

<Tabs>
  <Tab title="Connect Mode - Redirect">
    When `connect-mode="redirect"`, the response will be encoded as query string parameters and sent to the `redirect_url` page configured in the Fasten Connect Portal.

    ```
    https://www.example.com/callback?
    org_connection_id=1234-1234-1234-1234-1234&
    endpoint_id=1234-1234-1234-1234-1234&
    portal_id=4567-4567-4567-4567-4567&
    brand_id=7890-7890-7890-7890-7890&
    request_id=1234-1234-1234-1234-1234&
    external_id=user_12345
    external_state="unique-state-id"
    ```
  </Tab>

  <Tab title="Connect Mode - Popup">
    When `connect-mode="popup"`, the response will be sent to the parent window via a `orgConnectionCallback` event.

    ```html theme={null}
    <fasten-stitch
      public-id="public_test_xxxxxx"
      connect-mode="popup"
      popup-timeout="30"
      external-id="user_12345"
      external-state="unique-state-id"
    ></fasten-stitch>


    <script type="application/javascript">
      const el = document.querySelector('fasten-stitch');
      el.addEventListener('orgConnectionCallback', (event) => console.log(event.detail));
    </script>
    ```

    The response event will be in the following format:

    ```json theme={null}
    {
      "org_connection_id": "1234-1234-1234-1234-1234",
      "endpoint_id": "1234-1234-1234-1234-1234",
      "portal_id": "4567-4567-4567-4567-4567",
      "brand_id": "7890-7890-7890-7890-7890",
      "request_id": "1234-1234-1234-1234-1234",
      "external_id": "user_12345",
      "external_state": "unique-state-id"
    }
    ```
  </Tab>
</Tabs>

<ResponseField name="org_connection_id" type="string" required>
  Organization Connection Id is a unique identifier for the connection between the patient and the organization.
  You must store this value in your system to identify the patient in future API calls.
</ResponseField>

<ResponseField name="endpoint_id" type="string" required>
  Endpoint Id is a unique identifier for the endpoint that the patient has connected to.
  This value can be used to retrieve metadata about the endpoint (e.g. name, description, endpoint url information, etc.)
</ResponseField>

<ResponseField name="portal_id" type="string" required>
  Portal Id is a unique identifier for the Portal that the patient has connected to.
  This value can be used to retrieve branding information about the institution
</ResponseField>

<ResponseField name="brand_id" type="string" required>
  Brand Id is a unique identifier for the Brand that the patient has connected to.
  This value can be used to retrieve branding information about the institution
</ResponseField>

<ResponseField name="connection_status" type="string" required>
  The status of the connection. Possible values are `authorized`, `rejected`.
</ResponseField>

<ResponseField name="platform_type" type="string" required>
  An identifier for the EHR type associated with the connected endpoint.
</ResponseField>

<ResponseField path="request-id" type="string">
  An correlation id. This should be sent with any support ticket queries to the Fasten Connect support team.
</ResponseField>

<ResponseField name="external_id" type="string">
  (Optional) An Opaque identifier, used to identify the patient in your system.
  This value will be only be returned if it was previously provided to the stitch html element.
</ResponseField>

<ResponseField name="external_state" type="string">
  (Optional) An Opaque identifier, used to identify the connection request.
  This value will be only be returned if it was previously provided to the stitch html element.
</ResponseField>

# Error Response

Similar to the "Response" section above, when an error occurs during the health system connection an error payload will be provided to you, encoded in the query string parameters or as a browser event.

<Tabs>
  <Tab title="Connect Mode - Redirect">
    When `connect-mode="redirect"`, the error response will be encoded as query string parameters and sent to the `redirect_url` page configured in the Fasten Connect Portal.

    ```
    https://www.example.com/callback?
    error=invalid_request&
    error_description=The+request+is+missing+a+required+parameter&
    request_id=1234-1234-1234-1234-1234&
    external_state="unique-state-id"
    ```
  </Tab>

  <Tab title="Connect Mode - Popup">
    When `connect-mode="popup"`, the response will be sent to the parent window via a `orgConnectionCallback` event.

    ```html theme={null}
    <fasten-stitch
      public-id="public_test_xxxxxx"
      connect-mode="popup"
      popup-timeout="30"
      request_id="1234-1234-1234-1234-1234"
      external-id="user_12345"
      external-state="unique-state-id"
    ></fasten-stitch>


    <script type="application/javascript">
      const el = document.querySelector('fasten-stitch');
      el.addEventListener('orgConnectionCallback', (event) => console.log(event.detail));
    </script>
    ```

    The response event will be in the following format:

    ```json theme={null}
    {
      "error": "invalid_request",
      "error_description": "The request is missing a required parameter",
      "request_id": "1234-1234-1234-1234-1234",
      "external_state": "unique-state-id"
    }
    ```
  </Tab>
</Tabs>

<ResponseField name="error" type="string" required>
  The `error` parameter will contain a short string representing the error that occurred.

  For errors that occurred on the health system side, the possible values are:

  * `invalid_client`
  * `invalid_grant`
  * `unauthorized_client`
  * `unsupported_grant_type`
  * `invalid_scope`

  For errors that occurred on the Fasten Health side, the possible values are:

  * `fasten_unauthorized_client`
  * `fasten_invalid_request`
  * `fasten_server_error`
  * `fasten_token_exchange`
</ResponseField>

<ResponseField name="error_description" type="string" required>
  The `error_description` parameter can only include ASCII characters, and will be a sentence or two at most describing the circumstance of the error.
</ResponseField>

<ResponseField name="error_uri" type="string">
  The `error_uri` is an optional url parameter that may contain a link to the EHR's API documentation for more information.
</ResponseField>

<ResponseField name="request_id" type="string" required>
  Every error will have a unique `request_id`. When communicating with the Fasten Health development team, please
  provide the `request_id`, as it will make the debugging process much easier.
</ResponseField>

<ResponseField name="external_state" type="string">
  (Optional) An Opaque identifier, used to identify the connection request.
  This value will be only be returned if it was previously provided to the stitch html element.
</ResponseField>

# Javascript API

The stitch Web Component has a Javascript API that can be used to manipulate the modal popup.

## Methods

### show()

Shows the modal popup.

```javascript theme={null}
  window.addEventListener('DOMContentLoaded',function () {
    //show the modal using the element selector.
    document.querySelector('fasten-stitch').show();
  });
```

### hide()

Hide the modal popup.

```javascript theme={null}
  window.addEventListener('DOMContentLoaded',function () {
    ...

    //hide the modal using the element selector.
    document.querySelector('fasten-stitch').hide();
  });
```

## Events

When in `connect-mode="popup"` mode, the stitch component will emit the following events:

### orgConnectionCallback

This event is emitted when the user has successfully authenticated and the popup window has closed.

```javascript theme={null}
  window.addEventListener('DOMContentLoaded',function () {
    const el = document.querySelector('fasten-stitch');
    el.addEventListener('orgConnectionCallback', (event) => console.log(event.detail));
  });
```

# Styling

Styling the stitch Web Component is possible using CSS.
You can target the component using the `fasten-stitch` tag and select internal elements to apply custom styles.

```html theme={null}
  <style>
    fasten-stitch > button {
      background-color: green !important
    }
  </style>
```

The `!important` flag is required to override the default styles.