Skip to main content
The Connection class is the central entry point for interacting with Salesforce. It manages authentication, API requests, and provides access to all Salesforce resources.

​
Creating a Connection

​
Basic Connection

Create a connection with minimal configuration: 
const jsforce = require('jsforce');

const conn = new jsforce.Connection({
  version: '60.0'
});

​
Connection with Access Token

If you already have an access token: 
const conn = new jsforce.Connection({
  instanceUrl: 'https://yourinstance.salesforce.com',
  accessToken: 'your_access_token_here',
  version: '60.0'
});

​
Connection with Session ID

Using a session ID from SOAP login: 
const conn = new jsforce.Connection({
  serverUrl: 'https://yourinstance.salesforce.com/services/Soap/u/60.0',
  sessionId: 'your_session_id_here'
});

​
Configuration Options

The ConnectionConfig interface supports the following options:
​
version
string
default:"50.0"
Salesforce API version to use (e.g., ‘60.0’)
​
loginUrl
string
default:"https://login.salesforce.com"
Salesforce login URL. Use https://test.salesforce.com for sandboxes
​
instanceUrl
string
Instance URL obtained after authentication
​
accessToken
string
OAuth 2.0 access token for authenticated requests
​
refreshToken
string
OAuth 2.0 refresh token for automatic session refresh
​
sessionId
string
Session ID from SOAP login
​
serverUrl
string
Server URL from SOAP login response
​
oauth2
OAuth2 | OAuth2Config
OAuth2 configuration object or instance
​
maxRequest
number
default:"10"
Maximum number of concurrent parallel requests
​
logLevel
'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'NONE'
default:"NONE"
Logging level for debugging
​
callOptions
object
SOAP call options (client, defaultNamespace, etc.)
​
httpProxy
string
HTTP proxy URL for requests
​
refreshFn
SessionRefreshFunc
Custom function for refreshing sessions

​
Sandbox Connection

To connect to a Salesforce sandbox environment: 
const conn = new jsforce.Connection({
  loginUrl: 'https://test.salesforce.com',
  version: '60.0'
});

await conn.login('[email protected]', 'password');

​
Connection with Proxy

const conn = new jsforce.Connection({
  httpProxy: 'http://proxy.company.com:8080',
  version: '60.0'
});

​
Session Management

​
Accessing Session Information

After authentication, the connection stores session details: 
console.log(conn.accessToken);   // OAuth access token
console.log(conn.instanceUrl);   // Salesforce instance URL
console.log(conn.version);       // API version in use

// User information
if (conn.userInfo) {
  console.log(conn.userInfo.id);              // User ID
  console.log(conn.userInfo.organizationId);  // Organization ID
  console.log(conn.userInfo.url);             // Identity URL
}

​
API Usage Limits

The connection automatically tracks API usage limits: 
const result = await conn.query('SELECT Id FROM Account LIMIT 10');

// Check API usage after request
if (conn.limitInfo.apiUsage) {
  console.log(`API Calls: ${conn.limitInfo.apiUsage.used}/${conn.limitInfo.apiUsage.limit}`);
}

​
Identity Information

Retrieve detailed identity information: 
const identity = await conn.identity();

console.log(identity.user_id);
console.log(identity.organization_id);
console.log(identity.username);
console.log(identity.display_name);

​
Automatic Session Refresh

JSForce can automatically refresh expired sessions when using OAuth2: 
const conn = new jsforce.Connection({
  oauth2: {
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
    redirectUri: 'http://localhost:3000/callback'
  },
  instanceUrl: 'https://yourinstance.salesforce.com',
  accessToken: 'initial_access_token',
  refreshToken: 'your_refresh_token',
  version: '60.0'
});

// Session will be automatically refreshed if expired
const accounts = await conn.query('SELECT Id FROM Account');
Automatic session refresh only works when both refreshToken and OAuth2 client credentials are provided.

​
Custom Session Refresh

Implement custom session refresh logic: 
const conn = new jsforce.Connection({
  instanceUrl: 'https://yourinstance.salesforce.com',
  accessToken: 'initial_access_token',
  refreshFn: async (conn, callback) => {
    try {
      // Custom logic to obtain new access token
      const newToken = await getNewAccessToken();
      
      // Update connection with new token
      conn.accessToken = newToken;
      
      callback(null, newToken);
    } catch (error) {
      callback(error);
    }
  },
  version: '60.0'
});

​
Making HTTP Requests

The connection provides methods for making direct REST API requests: 
const result = await conn.request({
  method: 'GET',
  url: '/sobjects/Account/describe'
});

​
Convenience Request Methods

// GET request
const data = await conn.requestGet('/sobjects/Account/describe');

// POST request with JSON body
const account = await conn.requestPost('/sobjects/Account', {
  Name: 'New Account'
});

// PATCH request
const updated = await conn.requestPatch('/sobjects/Account/001xx000003DHP0', {
  Name: 'Updated Name'
});

// DELETE request
await conn.requestDelete('/sobjects/Account/001xx000003DHP0');

​
Connection Events

Listen to connection lifecycle events: 
const jsforce = require('jsforce');

// Global connection creation event
jsforce.on('connection:new', (conn) => {
  console.log('New connection created');
});

const conn = new jsforce.Connection();

​
Logging

Enable logging for debugging: 
const conn = new jsforce.Connection({
  logLevel: 'DEBUG',
  version: '60.0'
});

// Logs will show:
// - SOQL queries
// - API requests and responses
// - Authentication flows
// - Error details
Avoid using ‘DEBUG’ log level in production as it may expose sensitive information.

​
Best Practices

1

Always specify API version

Explicitly set the API version to ensure consistent behavior:
const conn = new jsforce.Connection({ version: '60.0' });
2

Use environment variables for credentials

Never hardcode credentials in your source code:
const conn = new jsforce.Connection({
  loginUrl: process.env.SF_LOGIN_URL,
  version: process.env.SF_API_VERSION
});
3

Handle session expiration

Implement refresh tokens or session refresh logic for long-running applications:
const conn = new jsforce.Connection({
  refreshToken: process.env.SF_REFRESH_TOKEN,
  oauth2: {
    clientId: process.env.SF_CLIENT_ID,
    clientSecret: process.env.SF_CLIENT_SECRET
  }
});
4

Monitor API limits

Check conn.limitInfo after operations to track API usage

​
Next Steps

Authentication

Learn about different authentication methods

Queries

Execute SOQL queries to retrieve data

CRUD Operations

Create, read, update, and delete records

API Reference

Complete Connection API reference

Build docs developers (and LLMs) love

Get started for freeTalk to us