Employee Agent Authentication in React Native

Learn how to authenticate users for Employee Agent mode using the Salesforce Mobile SDK integration or direct tokens.

Overview

Employee Agent authentication supports two approaches:

Bridge Auth (via Mobile SDK)

The Salesforce Mobile SDK handles the OAuth login flow natively. This is the recommended approach for production apps.

1JS calls loginForEmployeeAgent()
2  → EmployeeAgentAuthBridge.login()
3    → SalesforceSDKManager shows OAuth login screen
4      → User logs in
5    → Returns AuthCredentials to JS
6  → JS passes credentials to AgentforceService.configure()

Direct Token

You provide an OAuth accessToken directly in the EmployeeAgentConfig. This is useful for development, testing, or when your app manages its own auth flow.

Mobile SDK Integration

To use the Mobile SDK for authentication, configure your project for each platform.

iOS Setup

Use the WithMobileSDK subspec in your Podfile:

1pod 'ReactNativeAgentforce/WithMobileSDK', :path => '../node_modules/@salesforce/react-native-agentforce/ios'

This adds a dependency on SalesforceSDKCore, which provides OAuth login/logout flows, user account management, and token storage and refresh.

Android Setup

Add SalesforceReact as a runtime dependency in your android/app/build.gradle:

1dependencies {
2    implementation "com.salesforce.mobilesdk:SalesforceReact:13.1.1"
3}

The bridge library declares SalesforceReact as compileOnly. Your host app must provide the dependency at runtime.

AgentforcePackage uses reflection to detect if SalesforceSDKManager is on the classpath. If found, EmployeeAgentAuthBridge is registered as a native module. If not, Employee Agent auth is gracefully disabled.

Auth Functions

All auth functions are exported directly from the package:

1import {
2  isEmployeeAgentAuthSupported,
3  isEmployeeAgentAuthReady,
4  hasEmployeeAgentSession,
5  loginForEmployeeAgent,
6  logoutEmployeeAgent,
7  getEmployeeAgentCredentials,
8  refreshEmployeeAgentCredentials,
9} from "@salesforce/react-native-agentforce";

isEmployeeAgentAuthSupported()

Returns true if the build includes Mobile SDK and the EmployeeAgentAuthBridge native module is available. Use this to conditionally show/hide Employee Agent UI in your app.

1const supported = await isEmployeeAgentAuthSupported();

hasEmployeeAgentSession()

Returns true if the user is currently logged in with valid credentials.

1const loggedIn = await hasEmployeeAgentSession();

loginForEmployeeAgent()

Launches the Mobile SDK’s OAuth login flow. Returns AuthCredentials on success.

1try {
2  const creds = await loginForEmployeeAgent();
3  console.log("Logged in:", creds.userId);
4} catch (error) {
5  // User cancelled, auth bridge unavailable, or login failed
6  console.error("Login failed:", error);
7}

logoutEmployeeAgent()

Logs out the current user via Mobile SDK. Clears stored credentials and tokens.

1await logoutEmployeeAgent();

getEmployeeAgentCredentials()

Returns the current auth credentials if the user is logged in, or null if no session exists.

1const creds = await getEmployeeAgentCredentials();
2if (creds) {
3  console.log(`Logged in as ${creds.userId}`);
4}

refreshEmployeeAgentCredentials()

Asks the Mobile SDK to refresh the current session and returns new credentials.

1const newCreds = await refreshEmployeeAgentCredentials();

AuthCredentials Interface

1interface AuthCredentials {
2  instanceUrl: string; // Salesforce instance URL
3  organizationId: string; // Org ID
4  userId: string; // User ID
5  accessToken: string; // Current OAuth access token
6  refreshToken?: string; // Refresh token (may not be available on all platforms)
7}

Complete Login Flow

Here’s a complete login flow for Employee Agent with Mobile SDK:

1import {
2  AgentforceService,
3  isEmployeeAgentAuthSupported,
4  hasEmployeeAgentSession,
5  loginForEmployeeAgent,
6  getEmployeeAgentCredentials,
7} from "@salesforce/react-native-agentforce";
8
9async function launchEmployeeAgent(agentId?: string) {
10  // Step 1: Check if auth bridge is available
11  const authSupported = await isEmployeeAgentAuthSupported();
12  if (!authSupported) {
13    throw new Error("Employee Agent auth is not available in this build.");
14  }
15
16  // Step 2: Check for existing session, or login
17  let creds = await getEmployeeAgentCredentials();
18  if (!creds) {
19    creds = await loginForEmployeeAgent();
20  }
21
22  // Step 3: Get stored agent ID (or use provided one)
23  const resolvedAgentId = agentId || (await AgentforceService.getEmployeeAgentId());
24
25  // Step 4: Configure Employee Agent
26  await AgentforceService.configure({
27    type: "employee",
28    instanceUrl: creds.instanceUrl,
29    organizationId: creds.organizationId,
30    userId: creds.userId,
31    agentId: resolvedAgentId || undefined,
32    accessToken: creds.accessToken,
33  });
34
35  // Step 5: Launch conversation
36  await AgentforceService.launchConversation();
37}

Token Refresh

The SDK supports both automatic and manual token refresh.

Automatic Refresh

The native SDK automatically fetches fresh tokens from the Mobile SDK when the current token expires. The UnifiedCredentialProvider on both platforms integrates with the Mobile SDK’s user account system.

Manual Refresh

For scenarios where you need explicit control:

1try {
2  const newCreds = await refreshEmployeeAgentCredentials();
3  console.log("New access token:", newCreds.accessToken);
4
5  // Optionally reconfigure with new token
6  await AgentforceService.configure({
7    type: "employee",
8    instanceUrl: newCreds.instanceUrl,
9    organizationId: newCreds.organizationId,
10    userId: newCreds.userId,
11    accessToken: newCreds.accessToken,
12  });
13} catch (error) {
14  // Token refresh failed -- may need to re-login
15  console.error("Refresh failed:", error);
16}

Direct Token Mode

If you don’t want to integrate the Mobile SDK but still need Employee Agent functionality, you can provide tokens directly:

1// Obtain token through your own auth mechanism
2const token = await myAuthService.getAccessToken();
3
4await AgentforceService.configure({
5  type: "employee",
6  instanceUrl: "https://myorg.my.salesforce.com",
7  organizationId: "00Dxx0000001234",
8  userId: "005xx0000001234",
9  agentId: "0Xxxx0000001234",
10  accessToken: token,
11});
12
13await AgentforceService.launchConversation();

In this mode:

isEmployeeAgentAuthSupported() returns false.
You’re responsible for obtaining, storing, and refreshing tokens.
The native SDK won’t automatically refresh the token.
When the token expires, the conversation may fail. You’ll need to obtain a new token and call configure() again.

Local Config Override File

For development and testing, you can create a local configuration file that contains your Employee Agent settings and is not committed to source control.

Create src/config/employeeAgentConfig.local.ts:

1import type { EmployeeAgentConfig } from "@salesforce/react-native-agentforce";
2
3export const EMPLOYEE_AGENT_ENABLED = true;
4
5export const EMPLOYEE_AGENT_CONFIG: EmployeeAgentConfig = {
6  type: "employee",
7  instanceUrl: "https://my-dev-org.my.salesforce.com",
8  organizationId: "00Dxx0000001234",
9  userId: "005xx0000001234",
10  accessToken: "dev_access_token_here",
11};
12
13export function isEmployeeAgentConfigValid(): boolean {
14  return (
15    !!EMPLOYEE_AGENT_CONFIG.instanceUrl &&
16    !!EMPLOYEE_AGENT_CONFIG.organizationId &&
17    !!EMPLOYEE_AGENT_CONFIG.userId
18  );
19}

The bridge package exports these constants and the validation function. If the local override file exists, its exports are used; otherwise, defaults are returned (EMPLOYEE_AGENT_ENABLED: false, empty config).

Add the file to your .gitignore:

1# Employee Agent local config (contains tokens)
2**/employeeAgentConfig.local.ts

For more details on these exports, see the Authentication Reference in the React Native SDK reference documentation.

Session Management

Use these functions to check and manage the user’s authentication session.

Checking Session State

1// Is auth available in this build?
2const supported = await isEmployeeAgentAuthSupported();
3
4// Is the user currently logged in?
5const loggedIn = await hasEmployeeAgentSession();
6
7// Get full credentials (or null)
8const creds = await getEmployeeAgentCredentials();

Logout

1async function handleLogout() {
2  // Close any active conversation
3  await AgentforceService.closeConversation();
4
5  // Logout via Mobile SDK
6  await logoutEmployeeAgent();
7
8  // Reset SDK state
9  await AgentforceService.resetSettings();
10}

Session Persistence

The Mobile SDK handles session persistence natively. Tokens are stored securely and survive app restarts. The EmployeeAgentAuthBridge delegates all storage to the Mobile SDK.