Enable OAuth Username-Password Flow via API Settings

IGo to Setup > Identity > OAuth and OpenID Connect Settings.

Make sure Allow OAth Username-Password Flows is On

Option 1: Use Existing User Account

Step 1: Configure Salesforce for API Access

To authenticate with Salesforce and access its API, you need to create a Connected App in Salesforce and configure user permissions.

1. Create a Connected App in Salesforce

Log into your Salesforce Admin account at
https://XXXXXXXX.my.salesforce.com.
Navigate to Setup (click the gear icon in the top-right and select Setup).
In the left sidebar, search for App Manager and open it.
Click New Connected App (top-right).If you don't see the New Connected App Button go to External Client Apps -> Settings:
Select Create a Connected App and click Continue.
Fill in the Basic Information section:
- App Name: HeavySet Integration
- API Name: HeavySet_Integration
- Contact Email: Your email
Enable OAuth Settings:
- ✅ Check "Enable OAuth Settings".
- Callback URL: Set this to a placeholder, e.g., https://admin.heavyset.tech/lightning (this is not used for this authentication method).
- Selected OAuth Scopes (move these to the selected list):
  - Full access (full)
  - Perform requests on your behalf at any time (refresh_token, offline_access)
  - Manage user data via APIs (api)or Access and Manage your data (api)
  - Access your basic information (id, profile, email, address, phone)
Uncheck Require Secret for Refresh Token Flow
Click Save and Continue.
- ⚠️ Note: It may take 10-15 minutes for changes to propagate.

2. Retrieve API Credentials

Once the Connected App is created:

Go to App Manager.
Find your app (HeavySet Integration) and click View.
Click Manage Consumer Details
Copy the following:
- Consumer Key → This is your Client ID.
- Consumer Secret → Click "Click to reveal" and copy your Client Secret.

3. Set Up OAuth and API Permissions

Navigate to Setup > Users > Profiles.
Edit the profile of the user you’ll be authenticating with. (Your user may already be assigned a profile with all of these permissions enabled)
Ensure "API Enabled" is checked under Administrative Permissions.
Assign the required permissions by enabling:
- ✅ Modify All Data (for full CRUD access)
- ✅ View All Data (for read access to all objects)
- ✅ Customize Application (needed for some metadata access)
- ✅ View Setup and Configuration (to read object metadata)

Step 2: Retrieve All Required Authentication Credentials

Now that you’ve set up the Connected App and configured API permissions, you need to gather the credentials required for authentication.

Option A: Use a Security Token (Recommended for Most Cases)

If IP restrictions are enforced, you must use a Security Token with the password.

Get the Security Token
- Log into Salesforce as the HeavySet API User.
- Click your profile picture (top-right) > Settings.
- Navigate to My Personal Information > Reset My Security Token.
- Click Reset Security Token.
- Salesforce will email a new security token to the user’s email.
- Copy and save it (you’ll need to append this to the password when logging in via API).
Final API Authentication Credentials (Security Token Required)
- Client ID (Consumer Key)
- Client Secret (Consumer Secret)
- Username (hst_api@yourcompany.com or whatever you set)
- Password (set when creating the user)
- Security Token (retrieved via email)
🔹 When using the security token, you must append it to the password when logging in:

nginx

PASSWORD + SECURITY_TOKEN

Option B: Relax IP Restrictions (No Security Token Required)

If you do not want to use a Security Token, you can configure Salesforce to relax IP restrictions or whitelist your server's IP.

1. Relax IP Restrictions for the Connected App

Log into Salesforce as Admin.
Navigate to Setup.
Search for App Manager and open it.
Find HeavySet Integration, click the dropdown (▼), and select Manage.
Scroll down to OAuth Policies and find IP Relaxation.
Set it to:
- ✅ "Relax IP Restrictions" → Allows API logins from any IP without requiring a security token.

2. Final API Authentication Credentials (No Security Token Required)

Client ID (Consumer Key)
Client Secret (Consumer Secret)
Username (hst_api@yourcompany.com or whatever you set)
Password (set when creating the user)
No Security Token Needed (since IP restrictions are relaxed)

Which Option Should You Use?

Option	Pros	Cons
Use Security Token	More secure for unrestricted access	Must append the token to the password
Relax IP Restrictions	Easier, no need for a security token	Less secure if not whitelisting a static IP

🔹 For development/testing, relaxing IP restrictions can be convenient.
🔹 For production, using the Security Token is recommended unless your server has a static IP.

Option 2: Create New User Account

Step 1: Set Up a Dedicated API User for HeavySet Tech

Instead of using your Salesforce Admin account, it's a best practice to create a dedicated non-admin API user with the necessary permissions. This improves security, auditability, and ensures controlled access to your Salesforce instance.

1. Create a Dedicated User for API Access

Log into Salesforce Admin at (get this domain from the client)
https://XXXXXX.my.salesforce.com
Go to Setup (gear icon in the top-right corner).
In the left sidebar, search for Users and open Users > New User.
Fill in the new user details:
- First Name: HeavySet
- Last Name: Tech
- Alias: hst_api
- Email: Use a valid email you control (for password resets).
- Username: Something unique, e.g., hst_api@yourcompany.com
- Nickname: hstapi
- Role: Leave it blank or select a minimal role.
- User License: Salesforce
- Profile: Standard User (we will adjust permissions later).
Click Save.

Salesforce will send a Welcome Email with a temporary password. Log in using this new user, then reset the password as prompted.

If you do not receive a password email, use the "Login" button to login as that user and change the password under settings.

2. Assign API Permissions to the HeavySet API User

Now that the user is created, we need to give it full API access.

In Setup, go to Profiles (search for it in the sidebar).
Find the Standard User profile (or create a custom one) and click Edit.
Scroll to Administrative Permissions and ensure the following are checked:
- ✅ API Enabled
- ✅ Modify All Data (to read/write all objects)
- ✅ View All Data (to read all objects)
- ✅ Customize Application (needed for some metadata access)
- ✅ View Setup and Configuration (for metadata access)
- ✅ Password Never Expires (scroll to bottom of the page and select "User passwords expire in [Never expires]")
Click Save.

Alternatively, you can create a Custom Profile with only the permissions you need for better security.

3. Retrieve Security Token for HeavySet API User

Salesforce requires a Security Token when logging in via API.

Log into Salesforce as HeavySet API User.
Click your profile picture (top-right) > Settings.
Navigate to Reset My Security Token.
Click Reset Security Token.
Salesforce will email you a new security token.

Step 2: Create a Connected App for API Authentication

Now, we’ll create a Connected App to generate Client ID and Client Secret.

Log into Salesforce as Admin.
Go to Setup.
Search for App Manager and open it.
Click New Connected App (top-right).
Fill in the Basic Information:
- App Name: HeavySet Integration
- API Name: HeavySet_Integration
- Contact Email: Your email
Enable OAuth Settings:
- ✅ Check "Enable OAuth Settings"
- Callback URL: Set it to a placeholder like https://localhost/callback (won’t be used for this flow).
- Selected OAuth Scopes (Move these to the selected list):
  - Full access (full)
  - Perform requests on your behalf at any time (refresh_token, offline_access)
  - Access and manage your data (api)
  - Access your basic information (id, profile, email, address, phone)
Click Save and Continue.
- Important: It may take 10-15 minutes for the changes to propagate.
Go to App Manager, find HeavySet Integration, and click View.
Copy the following credentials:
- Consumer Key (Client ID)
- Consumer Secret (Client Secret)

Step 3: Gather All Required Credentials

Now you have:

Client ID (from Connected App)
Client Secret (from Connected App)
Username (hst_api@yourcompany.com)
Password (whatever you set)
Security Token (from email) (or relax IP Restrictions)

TroubleShooting

What to check	Why it matters
Password + security-token really match	The token must be appended every time the request comes from an IP that isn’t on a trusted range. A password reset or a “Reset Security Token” click invalidates the old token immediately.
User can still log in via the UI	If the user is Frozen, inactive, required to change password, or the password is wrong, you get `invalid_grant`. Try the same username/password in the normal Salesforce login page to rule this out.
Username-password flow is enabled in the Connected App	Connected App → OAuth & OpenID Connect Settings → Allow OAuth Username-Password Flows must be ON. If it’s off you always get `invalid_grant` no matter how perfect the credentials are.
The user is authorised for this Connected App	Connected App → Manage Profiles / Permission Sets. Add either the user’s profile or a permission set containing the user. If “Permitted Users” is “Admin approved users are pre-authorized”, missing assignment = `invalid_grant`.
IP/login-hour restrictions	If the profile has IP restrictions, or the Connected App’s OAuth Policies → IP Relaxation is “Enforce IP restrictions”, the same 401 shows up. Either relax the policy or add your server’s IP to Trusted IP Ranges.
Endpoint matches the org	Production → `https://login.salesforce.com`, Sandbox → `https://test.salesforce.com`. Hitting the wrong host returns `invalid_grant`.
No MFA challenge pending	If MFA is required and the user hasn’t set it up, username-password flow fails. Use a dedicated API-only user exempt from MFA or switch to the JWT flow.

Quick outside-the-code test

Run a cURL or Postman request with the five parameters. If that succeeds, the Connected App and user are set up correctly and the issue is likely a stale secret in your environment variables or deploy target.

curl https://login.salesforce.com/services/oauth2/token \
-d "grant_type=password" \
-d "client_id=$CLIENT_ID" \
-d "client_secret=$CLIENT_SECRET" \
-d "username=$USERNAME" \
-d "password=$PASSWORD$SECURITY_TOKEN"

Option 3: Client Credentials Flow (Recommended for Production)

The Client Credentials flow is the most secure option for server-to-server authentication. It doesn't require user credentials and is ideal for automated processes where no user interaction is possible.

Prerequisites

Before setting up Client Credentials flow, ensure:

You have Salesforce Admin access
Your Salesforce org supports the Client Credentials flow (available in Enterprise, Performance, Unlimited, and Developer editions)

Step 1: Enable Client Credentials in Org Settings

Enable OAuth Client Credentials Flow
- Go to Setup > Identity > OAuth and OpenID Connect Settings (or Setup -> Security Controls -> OAuth and OpenID Connect Settings for legacy)
- Make sure Allow OAuth Client Credentials Flow is On
- Click Save

Step 2: Create Connected App for Client Credentials

In Setup go to PLATFORM TOOLS -> Apps -> External Client Apps -> Settings and turn On Allow creation of connected apps. (You'll need to be in Lightning.)
In this same section click the New Connected App button to create a new connected app.

Configure Basic Information

App Name: HeavySet Integration (Client Credentials)
API Name: HeavySet_Integration_CC
Contact Email: Your email address

Configure OAuth Settings
- ✅ Check "Enable OAuth Settings"
- Callback URL: https://admin.heavyset.tech/oauth/callback (required but not used)
- Selected OAuth Scopes (move these to the selected list):
  - Full access (full)
  - Perform requests on your behalf at any time (refresh_token, offline_access)
  - Manage user data via APIs (api)or Access and Manage your data (api)
  - Access your basic information (id, profile, email, address, phone)
Enable Client Credentials Flow
- ✅ Check "Enable Client Credentials Flow"
- Run As: Select a dedicated user account (see Step 3)
- Click Save and Continue

⚠️ Note: Changes may take 10-15 minutes to propagate.

Step 3: Set Up the "Run As" User

Client Credentials flow requires a "Run As" user whose permissions determine what the integration can access.

Option A: Use Existing Admin User

Select your admin user as the "Run As" user
Ensure the user has API Enabled permission

Option B: Create Dedicated Integration User (Recommended)

Create Integration User

Go to Setup > Users > New User

Fill in details: (see above Option 2: Create New User Account)

First Name: HeavySet
Last Name: Integration
Alias: hst_int
Email: Your email address
Username: hst_integration@yourcompany.com
User License: Salesforce
Profile: System Administrator (or custom profile)

Save the user

Configure User Permissions
- Ensure the user profile has:
  - ✅ API Enabled
  - ✅ Modify All Data (or specific object permissions)
  - ✅ View All Data
  - ✅ View Setup and Configuration
Update Connected App
- Return to your Connected App
- Set Run As to your integration user
- Save changes

Step 4: Retrieve API Credentials

Get Client Credentials
- Go to App Manager
- Find "HeavySet Integration (Client Credentials)"
- Click View
- Click Manage Consumer Details
- Copy:
  - Consumer Key → This is your Client ID
  - Consumer Secret → This is your Client Secret

Step 5: Configure API Endpoint

For Client Credentials flow, use the appropriate Salesforce endpoint:

Production/Developer Orgs: https://login.salesforce.com/services/oauth2/token
Sandbox Orgs: https://test.salesforce.com/services/oauth2/token

Final API Authentication Credentials

You only need these two credentials:

Client ID: [Consumer Key from Connected App]
Client Secret: [Consumer Secret from Connected App]
Auth Method: client_credentials

No username, password, or security token required!

Test Your Configuration

Test the client credentials flow with cURL:

bash

curl https://login.salesforce.com/services/oauth2/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Expected Response:

json

{
  "access_token": "00D...",
  "instance_url": "https://yourorg.my.salesforce.com",
  "id": "https://login.salesforce.com/id/00D.../005...",
  "token_type": "Bearer",
  "issued_at": "1234567890",
  "signature": "..."
}

Troubleshooting Client Credentials Flow

Issue	Solution
"invalid_client_id"	Verify Client ID is correct and Connected App exists
"invalid_client"	Check that Client Credentials Flow is enabled in Connected App
"invalid_grant"	Ensure OAuth Client Credentials Flow is enabled in org settings
"insufficient_permissions"	Verify the "Run As" user has required permissions
"endpoint_error"	Confirm you're using the correct endpoint (login.salesforce.com vs test.salesforce.com)
"user_disabled"	Check that the "Run As" user is active and not frozen

Security Best Practices

Least Privilege: Only grant the minimum required permissions to the "Run As" user
Rotate Secrets: Regularly regenerate the Client Secret
Monitor Usage: Use Salesforce's Login History to monitor API usage
Environment Separation: Use different Connected Apps for different environments
IP Restrictions: Consider adding IP restrictions to the Connected App for additional security

Advantages of Client Credentials Flow

✅ No User Credentials: No need to manage usernames, passwords, or security tokens
✅ More Secure: Reduces credential exposure and eliminates password-based vulnerabilities
✅ Simpler Management: Only two credentials to manage
✅ Better for Automation: Ideal for server-to-server integrations
✅ No MFA Issues: Bypasses multi-factor authentication requirements
✅ Audit Trail: Clear audit trail showing which Connected App made requests

Option 4: External Client App with Credentials Flow (Recommended for Production and latest version of Salesforce)

Use this method when configuring Salesforce for HeavySet using the OAuth 2.0 Client Credentials flow. This approach is recommended for Production environments and for orgs using the latest Salesforce External Client App framework.

Step 1: Enable OAuth Client Credentials Flow in Org Settings

1. In Salesforce, navigate to Setup → Identity → OAuth and OpenID Connect Settings.

(Legacy path: Setup → Security Controls → OAuth and OpenID Connect Settings.)

2. Ensure 'Allow OAuth User-Agent Flows' is enabled.

3. Click Save.

Step 2: Configure the 'Run As' User

The Client Credentials flow requires a designated 'Run As' user. This user's permissions determine what data HeavySet can access via the API.

Option A: Use an Existing Admin User

You may use an existing System Administrator user if appropriate for your environment.

Ensure the user has the following permissions:

• API Enabled

• Required object-level permissions for data access

Option B (Recommended): Create a Dedicated Integration User

1. Navigate to Setup → Users → New User.

2. Create the user with the following example values:

• First Name: HeavySet

• Last Name: Integration

• Alias: hst_int

• Email: Your email address

• Username: hst_integration@yourcompany.com

• User License: Salesforce

• Profile: System Administrator (or scoped custom profile)

3. Save the user.

Ensure the user profile includes:

• API Enabled

• View All Data (or required object permissions)

• Modify All Data (if full access is required)

• View Setup and Configuration (if required)

Best Practice: Follow the principle of least privilege and grant only the permissions required for the HeavySet integration.

Step 3: Create the External Client App

You must be in Lightning Experience to complete this step.

Navigate to Setup → Platform Tools → Apps → External Client Apps → External Client App Manager.

Click New External Client App.

Configure the basic information:

• External Client App Name: HeavySet Integration (Client Credentials)

• API Name: HeavySet_Integration_CC

• Contact Email: Your email address

• Distribution State: Local

Under API (Enable OAuth Settings):

• Check Enable OAuth.

• Callback URL: https://admin.heavyset.tech/oauth/callback (required but not used for Client Credentials).

Select the following OAuth Scopes:

• Full access (full)

• Perform requests at any time (refresh_token, offline_access)

• Manage user data via APIs (api)

• Access identity URL service (id, profile, email, address, phone)

Under Flow Enablement:

• Enable Client Credentials Flow

Under Security:

• Require secret for Web Server Flow

• Require secret for Refresh Token Flow

• Enable Refresh Token Rotation

• Uncheck 'Require Proof Key for Code Exchange (PKCE)'

Click Create.

After creation, return to External Client App Manager and open the new app.

Go to Policies → Edit.

• Enable Client Credentials Flow

• Enter the username/email of the Run As user created in Step 2

Click Save.

Step 4: Retrieve Client ID and Client Secret

Open the External Client App → Settings → OAuth Settings → Consumer Key and Secret.

Copy the following credentials:

• Consumer Key (Client ID)

• Consumer Secret (Client Secret)

If Multi-Factor Authentication (MFA) is enabled, complete verification before accessing the credentials.

Step 5: Configure the Token Endpoint

Use your My Domain URL. In Setup, search for 'My Domain' to confirm your domain value.

Token Endpoint Format (Production and Sandbox):

https://{MyDomain}.my.salesforce.com/services/oauth2/token

Final API Authentication Details

Client ID: Consumer Key

Client Secret: Consumer Secret

Grant Type: client_credentials

No username, password, or security token is required.

Testing the Configuration

Example cURL request:

curl https://login.salesforce.com/services/oauth2/token \

-X POST \

-H 'Content-Type: application/x-www-form-urlencoded' \

-d 'grant_type=client_credentials' \

-d 'client_id=YOUR_CLIENT_ID' \

-d 'client_secret=YOUR_CLIENT_SECRET'

Security Best Practices

• Grant only the minimum required permissions to the Run As user.

• Rotate the Client Secret regularly.

• Monitor API usage using Salesforce Login History.

• Use separate External Client Apps for Production and Sandbox environments.

• Apply IP restrictions where appropriate.

Related to

Enable OAuth Username-Password Flow via API Settings

Option 1: Use Existing User Account

Step 1: Configure Salesforce for API Access

1. Create a Connected App in Salesforce

2. Retrieve API Credentials

3. Set Up OAuth and API Permissions

Step 2: Retrieve All Required Authentication Credentials

Option A: Use a Security Token (Recommended for Most Cases)

Option B: Relax IP Restrictions (No Security Token Required)

1. Relax IP Restrictions for the Connected App

2. Final API Authentication Credentials (No Security Token Required)

Which Option Should You Use?

Option 2: Create New User Account

Step 1: Set Up a Dedicated API User for HeavySet Tech

1. Create a Dedicated User for API Access

2. Assign API Permissions to the HeavySet API User

3. Retrieve Security Token for HeavySet API User

Step 2: Create a Connected App for API Authentication

Step 3: Gather All Required Credentials

TroubleShooting

Quick outside-the-code test

Option 3: Client Credentials Flow (Recommended for Production)

Prerequisites

Step 1: Enable Client Credentials in Org Settings

Step 2: Create Connected App for Client Credentials

Step 3: Set Up the "Run As" User

Option A: Use Existing Admin User

Option B: Create Dedicated Integration User (Recommended)

Step 4: Retrieve API Credentials

Step 5: Configure API Endpoint

Final API Authentication Credentials

Test Your Configuration

Troubleshooting Client Credentials Flow

Security Best Practices

Advantages of Client Credentials Flow

Option 4: External Client App with Credentials Flow (Recommended for Production and latest version of Salesforce)

Step 1: Enable OAuth Client Credentials Flow in Org Settings

Step 2: Configure the 'Run As' User

Option A: Use an Existing Admin User

Option B (Recommended): Create a Dedicated Integration User

Step 3: Create the External Client App

Step 4: Retrieve Client ID and Client Secret

Step 5: Configure the Token Endpoint

Final API Authentication Details

Testing the Configuration

Security Best Practices

Related articles