API Reference

Complete reference for the @getpassage/web-react SDK.

React API

PassageProvider

Context provider that renders the App Clip modal and manages WebSocket connections. Wrap your app or the relevant subtree.


import { PassageProvider } from "@getpassage/web-react";
 
<PassageProvider>
  <App />
</PassageProvider>;

Prop	Type	Default	Description
`children`	`ReactNode`	—	Child components

usePassage

Hook that returns functions to control the App Clip modal. Must be used within a PassageProvider.


import { usePassage } from "@getpassage/web-react";
 
const { openAppClip, close } = usePassage();

Field	Type	Description
`openAppClip`	`(options: OpenAppClipOptions) => void`	Open the modal and start monitoring link status. Shows a QR code on desktop or a “Connect” button on iOS.
`close`	`() => void`	Close the modal and stop monitoring

Types

OpenAppClipOptions

Options passed to openAppClip().

Field	Type	Required	Description
`claimCode`	`string`	Yes	Claim code from `POST /v1/links` (e.g. `"clm_xxx"`)
`onConnectionComplete`	`() => void`	No	Called when the link reaches `complete` status
`onConnectionError`	`(error: PassageErrorData) => void`	No	Called when the link reaches `failed` or `expired` status
`onClose`	`() => void`	No	Called when the user manually dismisses the modal (not fired on connection complete/error)

PassageErrorData

Error object passed to onConnectionError.

Field	Type	Description
`error`	`string`	Error message
`code`	`string \| undefined`	Error code (e.g. `"AUTOMATION_ERROR"`, `"CLIENT_TIMEOUT"`)

Standalone API

For non-React usage or imperative control outside of React components. These functions dispatch DOM events that PassageProvider listens for, so a provider must still be mounted in the React tree.

openAppClip

Open the App Clip modal. Dispatches a DOM event that PassageProvider handles.


import { openAppClip } from "@getpassage/web-react";
 
openAppClip({
  claimCode: "clm_xxx",
  onConnectionComplete: () => console.log("done"),
  onConnectionError: (err) => console.error(err),
  onClose: () => console.log("user dismissed modal"),
});

close

Close the modal and stop monitoring.


import { close } from "@getpassage/web-react";
 
close();

Next steps

Quickstart — Step-by-step integration guide
Create Link API — Link creation endpoint
Error Codes — Common error codes