phonelink/web
API reference for the Phonelink web client.
Exports
The phonelink/web entry point exports the following:
| Export | Type | Description |
|---|---|---|
phonelink | object | Web client with verify and getResult methods |
usePhonelink | function | React hook for the full verification flow |
PhonelinkPayload | type | TypeScript type for the decoded JWT payload |
phonelink.verify(clientId, callbackUrl)
Starts the phone verification flow by redirecting to Phonelink.
| Parameter | Type | Description |
|---|---|---|
clientId | string | Your Phonelink client ID |
callbackUrl | string | URL to redirect back to after verification |
Returns: void
Generates a 32-byte cryptographic nonce, stores it in sessionStorage under the key phonelink_nonce, and redirects the browser to https://phone.link/auth with the client ID, callback URL, and nonce as query parameters.
phonelink.getResult()
Reads the verification result on the callback page.
Parameters: none
Returns: { token: string; nonce: string } | null
Extracts the token from the URL query parameters and retrieves the nonce from sessionStorage. Removes the nonce from storage after retrieval. Returns null if no token is found in the URL or if the nonce is missing from storage.
usePhonelink(options)
React hook that manages the full verification flow.
Options
| Property | Type | Description |
|---|---|---|
clientId | string | Your Phonelink client ID |
callbackUrl | string | URL to redirect back to after verification |
Return value
| Property | Type | Description |
|---|---|---|
verify | () => void | Initiates the verification flow |
result | { token: string; nonce: string } | null | Verification result, or null |
isCallback | boolean | Whether the current page is the callback page |
On mount, the hook calls getResult() to check for a token in the URL. If found, result is populated and isCallback is true. The verify function is memoized with useCallback and only changes when clientId or callbackUrl change.
PhonelinkPayload
TypeScript interface for the decoded JWT payload. See Server API Reference for the full property list.
import type { PhonelinkPayload } from "phonelink/web";