Externalizing User Management

---

At a Glance

• Your system controls registration and login.
• Air Doctor accepts an external token.
• Air Doctor hides all account-management screens.
• You set embedded=true.
• Air Doctor sends ready.
• Your system responds with token={TOKEN}.

External user management instructs the Air Doctor app to accept session credentials from your system and disable all internal account-management screens. This article describes how to complete this setup.

User Flow Overview

1. Host loads the Air Doctor application with the embedded directive.
2. Air Doctor sends a ready message.
3. Host retrieves an access token.
4. Host delivers token={TOKEN} to Air Doctor.
5. Air Doctor authenticates the user inside the embedded frame.

This sequence externalizes all identity workflows and assigns account ownership to your system.

Token Exchange

By default, Air Doctor manages user accounts inside the embedded app. If you want your own system to handle user registration and login, you can externalize user management.

To run Air Doctor with credentials from an external source, complete the following steps:

Directive

• Specify the embedded directive — This directive instructs the app to wait for an external authentication token (see Directives below).

Readiness

• Wait for the app’s ready message — After the app loads, it sends a postMessage to indicate readiness to accept a token. The message contains the string ready.

Token Delivery

• Send the token — After you receive ready, respond with a message that contains a single string: token={TOKEN}. Replace {TOKEN} with the access token from your authentication system; this token is the same token you receive from Air Doctor servers on behalf of your user.

The Air Doctor app uses the provided token to authenticate the user and hide all account-management screens.

Quick Checklist

• Set embedded=true.
• Listen for the ready message.
• Retrieve access token from your system.
• Deliver token={TOKEN}.
• Confirm messaging bridge availability for each platform.
• Confirm that postMessage is not blocked by platform restrictions.

Example Token Exchange

Below is a conceptual example for a web integration that uses plain JavaScript:

<iframe id="airdoctor" src="https://www.air-dr.com/webapp/?embedded=true" style="width:100%; height:600px; border:none;"></iframe>

<script>
  const iframe = document.getElementById('airdoctor');

  // Listen for messages from Air Doctor
  window.addEventListener('message', (event) => {
    if (event.data === 'ready') {
      // Send token once Air Doctor is ready
      const token = obtainTokenFromYourAuthSystem();
      iframe.contentWindow.postMessage(`token=${token}`, '*');
    }
  });
</script>

Platform Communication

Platform	Communication Method
Web	window.parent.postMessage
iOS	window.webkit.messageHandlers.airdoctor
Android	window.AirDoctor

The reference implementation shows how each platform sends the token.

Reference Implementations

To simplify your integration, we maintain a public Git repository with sample projects for Level 2 integration. These examples show how to embed the Air Doctor WebView and handle the ready → token handshake in web and native code.

Retrieving Access Token

The end-user access token is available through the login function in our Open API. You call this function with a username and password (and MFA code, if user enabled) or, for a managed user, with only the username. To call this function for a managed user, the request must include the access token of the user’s manager (for example, the insurer admin token).