Client Integration

The Client SDK lets a web app opened in the Workbench obtain a one-time code; the app backend then completes passwordless sign-in. The SDK is loaded from a local file and does not exchange tokens, query user information, or create the business session.

Download and load the SDK

The SDK is not installed through npm. Download the UMD file and save it in the business system's static assets directory.

Download: twt-link-universal.umd.min.js

<script src="/assets/sdk/twt-link-universal.umd.min.js"></script>

After the script loads, use the public functions through window.__TWT_LINK__.

Integration flow

1. Create and publish an enterprise internal app in the admin console, then configure the in-container passwordless sign-in URL.
2. Download the SDK and save it in the business system's static assets directory.
3. Load the local SDK file with a <script> tag.
4. In the Workbench container, call requestWorkbenchAuthCode() to obtain a one-time code.
5. Submit the code to the app backend over HTTPS.
6. The backend uses the app credentials to call the Token and UserInfo APIs, obtains the current user information, and creates the business session.

Frontend example

The following example loads the local SDK, checks the Workbench environment, obtains a code, and submits it to the business backend:

<script src="/assets/sdk/twt-link-universal.umd.min.js"></script>
<script>
  async function loginFromWorkbench() {
    const sdk = window.__TWT_LINK__;

    // Use the business system's own sign-in flow in a regular browser.
    if (!sdk || !sdk.isTwtLinkPlateform()) {
      window.location.href = "/login";
      return;
    }

    const environment = sdk.getWorkbenchEnvironment();
    console.info("Current Workbench environment", environment.platform);

    try {
      // The code is single-use; send it to the business backend over HTTPS immediately.
      const { code } = await sdk.requestWorkbenchAuthCode({ timeoutMs: 5000 });
      const response = await fetch("/api/workbench/login", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ code }),
      });

      if (!response.ok) {
        throw new Error("Business sign-in failed. Request a new code.");
      }

      window.location.replace("/app");
    } catch (error) {
      // Do not resubmit an old code; request a new one before retrying.
      console.error("Workbench sign-in failed", error);
    }
  }

  loginFromWorkbench();
</script>

The SDK returns:

{ code: "one-time code" }

Do not write the code to a URL, log, Cookie, Local Storage, or other persistent storage. A regular browser does not support Workbench sign-in and should use the business system's own sign-in flow.

Backend processing

After receiving the frontend code, the business backend should:

1. Call POST /auth/v1/oauth/token with the server-side client_id and client_secret to obtain an app-level access_token.
2. Call POST /auth/v1/oauth/userinfo with the access_token and one-time code to obtain the current user information.
3. Create the business system's own session; subsequent business requests use that session.

Obtain the app-level access_token:

POST /auth/v1/oauth/token
Content-Type: application/json

{
  "client_id": "app ID",
  "client_secret": "app secret",
  "grant_type": "client_credentials"
}

Query the current user information:

POST /auth/v1/oauth/userinfo?access_token=<access_token>
Content-Type: application/x-www-form-urlencoded

code=<code>

Never send client_secret, access_token, or code to the frontend. Keep client_secret on the backend and discard the code immediately after exchange.

SDK functions

• isTwtLinkPlateform(): checks whether the page is running in a supported TWT Link Workbench client.
• getWorkbenchEnvironment(): returns the current client environment when the app needs to distinguish desktop and mobile clients.
• requestWorkbenchAuthCode(): obtains a one-time code; it accepts timeoutMs and AbortSignal, and the result should be sent to the app backend immediately.

Common issues

SDK errors are returned through AuthError.code. The table below lists the error codes currently defined by the SDK and recommended handling. Branch on the error code in business code; if you encounter an error not listed below, please contact us.

Error code	Common cause	Handling
SDK_ENVIRONMENT_UNSUPPORTED	The page is not running in a supported Workbench client, or the runtime information is incomplete.	Open the page in a supported Workbench client; use the business system's own sign-in flow in a regular browser.
AUTH_REQUEST_TIMEOUT	The current client or authorization chain did not respond within timeoutMs.	Check the network and Workbench status, then request a new code; do not submit a timed-out code.
AUTH_REQUEST_ABORTED	The caller canceled the request, or a new request replaced the current authorization request.	Do not treat it as a server failure; avoid duplicate clicks, check the request state, and request a new code if needed.
AUTH_REQUEST_PAGE_CHANGED	The page changed while authorization was in progress, or the authorization context became invalid.	Wait until the final page URL is stable, then call the SDK again; do not request a code during navigation or reload.
AUTH_REQUEST_IN_PROGRESS	An authorization request is already running on the same page.	Reuse or await the existing request and avoid concurrent calls to requestWorkbenchAuthCode().
AUTH_RESPONSE_INVALID	The current client response is missing required fields or failed response validation.	Confirm that the SDK and Workbench client versions match; keep the error code and request time, and contact us if needed.
INVALID_REQUEST	The current client or server considers the request parameters invalid, such as a missing or malformed body, app identifier, or current page URL.	Check the app configuration, in-container sign-in URL, and current page URL; do not modify SDK-internal request parameters.
INVALID_CLIENT	The app is unavailable, the page is outside the in-container sign-in URL scope, the origin does not match, or the user is outside the app visibility scope.	Check publication status, sign-in URL and origin settings, app visibility, and app credentials.
INVALID_TOKEN	The current-user credential injected by the gateway or current client is invalid.	Ask the user to sign in to the Workbench again, then request a new code.
SERVER_ERROR	A server dependency such as the database or cache failed, or an unrecognized server error occurred.	Retry later; if it persists, record the error code, time, and request identifier and contact the server team.
HOST_AUTH_REJECTED	The current client rejected authorization without returning a more specific error code.	Check the client sign-in state, app configuration, and visibility scope; contact us if the cause remains unclear.

The code is a one-time credential. Apart from the error code, request time, and request identifier needed for troubleshooting, do not log the code, access_token, or client_secret.

For the server-side passwordless sign-in API details, see Passwordless sign-in.