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 with a QR code and start monitoring link status
`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

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),
});

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