# Parallel Developer Documentation

**Legacy – v1.x**, which is no longer actively maintained.

For up-to-date documentation, see the **[latest version](https://developer.parallelmarkets.com/docs/javascript/events)** (Current – v2.x).

Version: Legacy – v1.x

## Subscribing to Events

The Parallel experience can be initiated in two ways:

- Via a call to `login()` directly
- A Parallel button click on a button shown after a call to `subscribeWithButton()` or `showButton()`

Once that experience is initiated, users are directed through a few steps:

1. The user will be asked to log in or create an account if they are not already logged in to Parallel Markets.
2. The user will be asked to consent to share information (if they have not previously provided consent) with you.
3. The user will be asked to provide information to fulfill any scopes you requested (if they haven't provided the information before). For instance, if you request the `accreditation_status` scope and a user does not have an active accreditation, they will be asked to complete an accreditation flow.
4. The user will complete the experience and the overlay will disappear (or the user will be redirected back to your site).

After these steps are completed, a few different events are fired by the SDK to provide you with the results of the user flow. You can subscribe to these events to know when a user has completed the steps.

For instance, to execute code whenever a user completes or cancels a flow:

- React Module
- ES Module
- Manual Loading

`AuthStatusChangeMessage` is a complete example component that subscribes to events and handles unsubscribing on unmount. `SimplerAuthStatusChangeMessage` demonstrates a simplification by pulling the `loginStatus` out of the `useParallel()` hook.

```jsx
import { useParallel } from '@parallelmarkets/react'
const AuthStatusChangeMessage = () => {
  const { parallel } = useParallel()
  const [status, setStatus] = useState(null)
  useEffect(() => {
    if (!parallel) return
    parallel.subscribe('auth.statusChange', setStatus)
    return () => {
      parallel.unsubscribe('auth.statusChange', setStatus)
    }
  }, [parallel])
  return status ? <p>Status changed to: {status.status}</p> : null
}
// simpler version of the above using the hook's existing subscription to auth status changes
const SimplerAuthStatusChangeMessage = () => {
  const { loginStatus } = useParallel()
  return loginStatus ? <p>Status changed to: {loginStatus.status}</p> : null
}
```

```js
// wait for the loading to finish before calling any functions
const parallel = await loadParallel({ client_id: '123', environment: 'demo', flow_type: 'overlay' })
parallel.subscribe('auth.statusChange', function (result) {
  if (result.status === 'connected') {
    // the user is logged in and you can call the API now
  } else if (result.status === 'not_authorized') {
    // the user canceled authentication or failed
    // to consent to sharing with your site
  } else {
    // the user authentication is unknown (i.e., the user
    // is not logged in) - so show the login button
    parallel.showButton()
  }
})
```

```js
Parallel.subscribe('auth.statusChange', function (result) {
  if (result.status === 'connected') {
    // the user is logged in and you can call the API now
  } else if (result.status === 'not_authorized') {
    // the user canceled authentication or failed
    // to consent to sharing with your site
  } else {
    // the user authentication is unknown (i.e., the user
    // is not logged in) - so show the login button
    Parallel.showButton()
  }
})
```

The only way to know when users have successfully authorized sharing their data with your site is to subscribe to an auth event (or use the `loginStatus` from the `useParallel` React hook). This is because a user may have authorized via a redirect flow, which fires an `auth.login` and an `auth.statusChange` event. 
Also note that authentication "status" refers to the user's status from the perspective of your site, not their authentication status on parallelmarkets.com or within the experience in the iframe that is embedded or shown in an overlay.

## Auth Events

The following events can be tracked using `Parallel.subscribe()`:

### List of Events  
| Event | Description |
| --- | --- |
| `auth.login` | Fires after a user authenticates (after a call to `Parallel.login()`) and completes all steps in the Parallel experience |
| `auth.logout` | Fires after a user is logged out via a call to `Parallel.logout()` |
| `auth.statusChange` | Fires when the user's authentication status changes after the full completion of the flow in a Parallel experience or when the user is logged out |
| `auth.authResponseChange` | Fires when the `authResponse` object has changed, which indicates that the user's access token has changed in some way. |

### Event Callback Arguments

When events are triggered, the `callback` function will be called with a single argument with details about the event. The argument will be an object with the following properties:

| Property | Description |
| --- | --- |
| status | This will be one of:<br>- `not_authorized`: The user declined to share the consent requested and canceled the process<br>- `unknown`: The user is not currently logged in from the perspective of your site<br>- `connected`: The user has authenticated and has consented to sharing data. You can now make calls to the [Parallel API](https://developer.parallelmarkets.com/docs/1.x/javascript/server-api). |
| error | An OAuth 2 error code (if an error occurred). |
| errorDescription | An error description (if an error occurred). |
| authResponse | If a user has authenticated and consented to sharing the requested data, this will contain an `access_token` and `refresh_token` (as well as the other fields described in the [Token API response](https://developer.parallelmarkets.com/docs/1.x/server/token-api#response-parameters)). |

For instance, here's a successful authentication / consent granted object:

```javascript
{
  status: "connected",
  authResponse: {
    access_token: "MVXoULzTSdmDINFf",
    token_type: "bearer",
    expires_in: 86400,
    refresh_token: "dmDINFfULzTSdMVXoU",
    refresh_expires_in: 345600
  }
}
```

And here's an example where a user declined consent:

```javascript
{
  status: 'not_authorized'
}
```

And here's an example object when the user is not currently logged in:

```javascript
{
  status: 'unknown'
}
```

## Handoff Events

### List of Events

| Event | Description |
| --- | --- |
| `handoff.entitySelected` | Fires when an entity has been selected by a user during the Parallel flow. This is only triggered if a `handoff_id` is provided in the `Parallel.login()` call for use with the [Handoff API](https://developer.parallelmarkets.com/docs/1.x/server/handoff-api).|

### Event Callback Arguments

| Property | Description |
| --- | --- |
| `handoff_id` | This will be the `handoff_id` that was originally passed to `Parallel.login()` |