Integrator client integration guide (Web SDK)
Add account enrollment and code verification to the integrator client. The integrator server verifies codes and completes the business operation.
1. Install
npm install @auth-link/web@latest
2. Implement submit
Use your application request method to submit the code to your server. Your project supplies verifyRequest in this example.
import type { Submit } from '@auth-link/web';
export function createSubmit(
verifyRequest: (
data: { passcode: string },
options: { signal: AbortSignal },
) => Promise<void>,
): Submit {
return async (passcode, { signal }) => {
await verifyRequest({ passcode }, { signal });
};
}
submit(passcode,{signal}) returns Promise<void>. Keep the code as a string to preserve leading zeros. Resolve after server verification and business completion; throw on request or business failure.
Forward signal to your request method to cancel waiting when the dialog closes or unmounts. For uncertain results, retry the original operation with the same idempotency key.
3. First enrollment: openBind
Get {qr,expiresAt} from your server, then call openBind. Pass the original QR JSON payload and server deadline. The server completes enrollment after the user scans and submits the code.
import { openBind } from '@auth-link/web';
import type { BindingTicket, BindOptions, Submit } from '@auth-link/web';
import '@auth-link/web/styles.css';
export function bindAccount(
ticket: BindingTicket,
submit: Submit,
onRefresh?: BindOptions['onRefresh'],
) {
return openBind({
qr: ticket.qr,
expiresAt: ticket.expiresAt,
submit,
onRefresh,
});
}
Provide onRefresh to request another QR. It runs when the QR has expired and the user selects refresh, returning a new {qr,expiresAt}.
4. Everyday verification: openVerify
Prepare the pending operation on your server, then call openVerify. Use submit to verify the six-digit code and onSuccess to update the page after success.
import { openVerify } from '@auth-link/web';
import type { Submit } from '@auth-link/web';
import '@auth-link/web/styles.css';
export function verifyAction(submit: Submit, onSuccess?: () => void) {
return openVerify({ submit, onSuccess });
}
5. Options and callbacks
| Option | Type | Description |
|---|---|---|
submit | (passcode, {signal}) => Promise<void> | Required. Submit the code and wait for server verification and business completion. |
qr | string | Required for enrollment. The original QR JSON string returned by the server. |
expiresAt | string | Required for enrollment, whose QR expires at most 60 minutes after creation. Optional for verification, as the server action deadline. |
onRefresh | ({signal}) => Promise<BindingTicket> | Optional for enrollment. Request and return a new {qr,expiresAt}. |
authLinkOrigin | string | Optional for enrollment. Validate the AuthLink service origin in the QR using your service configuration. |
onSuccess | () => void | Promise<void> | Optional. Update the UI after successful verification and dialog closure. |
onError | (error: Error) => void | Optional. Receive request or business errors. |
onClose | () => void | Optional. Run when the user closes the dialog or calls close(). |
onExpired | () => void | Promise<void> | Optional. Run when expiresAt is reached. |
locale | Locale | Optional. Set the interface language; defaults to zh-CN. |
Language codes: zh-CN, zh-TW, en, ja, bn, es, fil, hi, id, ms, pt, th, vi.
6. Modal methods
Both openBind and openVerify return an AuthLinkModal with these methods.
| Method | Description |
|---|---|
close() | Close the dialog, cancel waiting and call onClose. |
destroy() | Destroy the dialog and cancel waiting silently. |
retry() | Clear the error and allow the user to submit again. |
setLocale(locale) | Change the interface language while retaining the entered code. |
7. React / Vue
component options match the JavaScript methods. Use AuthLinkBind for enrollment and AuthLinkVerify for verification. Unmount after success or closure. Vue emits success, close, error and expired; onRefresh is a function prop.
React
"use client";
import { AuthLinkBind, AuthLinkVerify } from '@auth-link/web/react';
import type { BindingTicket, Submit } from '@auth-link/web';
import '@auth-link/web/styles.css';
export function Bind({ ticket, submit, onSuccess, onClose }: {
ticket: BindingTicket; submit: Submit;
onSuccess: () => void; onClose: () => void;
}) {
return <AuthLinkBind {...ticket} submit={submit}
onSuccess={onSuccess} onClose={onClose} />;
}
export function Verify({ submit, onSuccess, onClose }: {
submit: Submit; onSuccess: () => void; onClose: () => void;
}) {
return <AuthLinkVerify submit={submit}
onSuccess={onSuccess} onClose={onClose} />;
}
Vue
<script setup lang="ts">
import { AuthLinkVerify, AuthLinkBind } from '@auth-link/web/vue';
import type { Submit, BindingTicket } from '@auth-link/web';
import '@auth-link/web/styles.css';
defineProps<{ submit: Submit; ticket?: BindingTicket }>();
const emit = defineEmits<{ success: []; close: [] }>();
</script>
<template>
<AuthLinkBind v-if="ticket" v-bind="ticket" :submit="submit"
@success="emit('success')" @close="emit('close')" />
<AuthLinkVerify v-else :submit="submit"
@success="emit('success')" @close="emit('close')" />
</template>