Manage Virtual Presences

A virtual presence represents a connected user identity on an external platform (e.g., an email account).

Connecting a Virtual Presence

In order for the Privacy Interaction Service to scan a user's virtual presence, the user must grant the service access via OAuth 2.0. Your application obtains an OAuth credential from the provider and passes it to the SDK, which transmits it securely to the Privacy Interaction Service backend. The service then uses this credential to periodically access the connected account and discover data holders.

The SDK accepts credentials in one of two forms:

• Authorization code — A short-lived code obtained when the user completes the OAuth consent flow in your application. The Privacy Interaction Service exchanges this code server-side for an access token and refresh token, which it stores securely and uses for ongoing access.

• Refresh token — A long-lived credential your application has already obtained from a prior OAuth flow. Providing a refresh token directly allows the service to begin scanning without needing to perform the initial code exchange. This is useful when your application manages its own OAuth flow and already holds the user's credentials.

In both cases, the service uses the credential to obtain short-lived access tokens as needed. If the credential expires or is revoked by the user, the virtual presence transitions to the NEEDS_REAUTH state and your application should prompt the user to re-authenticate.

The required OAuth scopes and what data the service accesses depend on the virtual presence type. See Supported Virtual Presence Types for details.

Connect with Authorization Code

Use this method when your application has completed an OAuth flow and received an authorization code from the provider. The authorization code has enough information embedded to sufficiently identify the virtual presence.

Typescript

try {
  const virtualPresence = await privacyInteractionClient.connectVirtualPresenceWithAuthCode(
    authCode,
  )
  // The virtual presence is now connected.
  // `virtualPresence.state` will be `CONNECTED` or `SCANNING`.
} catch (error) {
  // Handle/notify user of errors
}

Connect with Refresh Token

Use this method when your application already holds a valid refresh token for the provider.

Typescript

try {
  const virtualPresence = await privacyInteractionClient.connectVirtualPresenceWithRefreshToken({
    refreshToken: 'refresh-token-value',
    providerIdentity: '[e-mail]',
    scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
    expiresInEpochMs: 1700000000000, // optional
  })
  // The virtual presence is now connected.
} catch (error) {
  // Handle/notify user of errors
}

Input Parameters:

Parameter	Type	Required	Description
refreshToken	string	Yes	The refresh token value.
providerIdentity	string	Yes	The identity associated with the provider (e.g., email address).
scopes	string[]	No	OAuth scopes associated with the token.
expiresInEpochMs	number	No	Token expiration time in milliseconds since epoch.

Disconnecting a Virtual Presence

To disconnect a virtual presence and stop it from being scanned, call disconnectVirtualPresence with the virtual presence's unique identifier.

When a virtual presence is disconnected, its state will transition to INACTIVE. Any existing data holders and analysis results associated with the virtual presence will remain accessible.

First Tab

try {
  const virtualPresence = await privacyInteractionClient.disconnectVirtualPresence(
    virtualPresenceId,
  )
  // The virtual presence is now disconnected.
  // `virtualPresence.state` will be `INACTIVE`.
} catch (error) {
  // Handle/notify user of errors
}

Listing Virtual Presences

To retrieve all virtual presences for the signed-in user, use the listVirtualPresences method. Results are paginated.

A call to listVirtualPresences returns a ListOutput object containing a list of matching items and a nextToken to support pagination. If no results are found, the result will contain empty items. Always check the value of the returned nextToken—there are no more results to retrieve when nextToken is undefined.

Typescript

try {
  const listOutput = await privacyInteractionClient.listVirtualPresences({
    limit: 20,
    nextToken: undefined,
  })
  // `listOutput.items` contains the virtual presences.
  // Page through results if `listOutput.nextToken` is defined.
} catch (error) {
  // Handle/notify user of errors
}

Input Parameters:

Parameter	Type	Required	Description
limit	number	No	Maximum number of items to return. Will be defaulted if omitted.
nextToken	string	No	A pagination token from a previous call.

Virtual Presence States

A virtual presence transitions through the following states:

State	Description
CONNECTED	The virtual presence is active and connected to the provider.
SCANNING	The virtual presence is currently being scanned for data holders.
NEEDS_REAUTH	The virtual presence requires re-authentication with the provider. This will happen automatically when the refresh token expires, or when the user explicitly disconnects the Privacy Interaction application from their provider.
ERROR	The virtual presence encountered an error and is in a failed state.
INACTIVE	The virtual presence has been disconnected and is no longer active.

When a virtual presence enters the NEEDS_REAUTH state, your application should prompt the user to re-authenticate with the provider and call connectVirtualPresenceWithAuthCode or connectVirtualPresenceWithRefreshToken again.

Supported Virtual Presence Types

Gmail Inbox

Property	Value
Provider type	EMAIL
Required OAuth scope	https://www.googleapis.com/auth/gmail.readonly
Provider identity	The user's Gmail address (e.g., [e-mail])

When connected with the gmail.readonly scope, the service scans email headers — sender addresses, subject lines, and metadata — to identify data holders (companies and services the user has interacted with). It does not read email body content.

The service periodically re-scans the inbox to discover new data holders as new emails arrive. Each scan updates the virtual presence's lastScannedAt timestamp.

Example: Connect with auth code (Gmail)

Typescript

// After the user completes Google's OAuth consent flow and you receive an auth code
// scoped to https://www.googleapis.com/auth/gmail.readonly
const virtualPresence = await privacyInteractionClient.connectVirtualPresenceWithAuthCode(
  authCode,
)

Example: Connect with refresh token (Gmail)

Typescript

const virtualPresence = await privacyInteractionClient.connectVirtualPresenceWithRefreshToken({
  refreshToken: 'refresh-token-value',
  providerIdentity: '[e-mail]',
  scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
})

Rescanning a Virtual Presence

Once a virtual presence is connected and the initial scan completes, you can trigger a rescan to discover new data holders that have appeared since the last scan. A rescan uses the stored credential - no new authorization from the user is required unless the credential has been revoked or expired. In this case, the virtual presence transitions to NEEDS_REAUTH and your application should prompt the user to re-authenticate.

Rescanning is incremental. New data holders are added to the existing set, and previously discovered data holders have their metadata updated. Existing data holders are never removed by a rescan. The virtual presence transitions to SCANNING while the rescan is in progress and returns to CONNECTED when complete.

To perform a rescan with default options, call the rescanVirtualPresence method with virtual presence's unique identifier. You can control the scope of a rescan by providing ScanOptions. This is useful for limiting how far back the scan reaches or excluding domains and categories the user is not interested in.

Typescript

try {
  const virtualPresence = await privacyInteractionClient.rescanVirtualPresence({
    id: virtualPresenceId,
    options: {
      earliestScanDate: '2026-01-01T00:00:00.000Z',
      maximumItemsProcessed: 200,
      excludeDomains: ['example.com', 'internal.org'],
    },
  })
} catch (error) {
  // Handle/notify user of errors
}

Input Parameters:

Parameter	Type	Required	Description
id	string	Yes	The unique identifier of the virtual presence to rescan.
options	ScanOptions	No	Options to control the rescan behavior.

Scan Options:

Parameter	Type	Description
maximumItemsProcessed	number	Maximum number of source items (e.g., emails) to process during the scan. When omitted, a service default is used.
earliestScanDate	string	Only consider items on or after this date (ISO 8601 string). Useful for narrowing the scan to recent activity.
latestScanDate	string	Only consider items on or before this date (ISO 8601 string).
excludeDomains	string[]	Domains to exclude from discovery results. Data holders matching these domains will be skipped.
excludeCategories	string[]	Provider-specific categories or labels to exclude from processing (e.g., to skip personal emails).

Subscribing to Virtual Presence Updates

To receive real-time notifications when a virtual presence changes state, see Subscriptions.