Install Guide / Step 2 of 5

Step 2: Create an External Client App

Datatrax connects to your Salesforce org using a Connected App (called an External Client App in newer API versions). You create this in your own org, which gives you full control over the OAuth credentials. This step takes about five minutes.

Prerequisites

Before you begin, complete these two requirements:

1. Assign the Datatrax Admin permission set to your user account. You'll need this to authorize the Salesforce connection in the Datatrax portal later. (See Step 6: Controlling Access for permission set setup instructions.)
2. Generate a certificate and private key locally. You'll upload the certificate here when enabling JWT Bearer Flow below.

   Generate a self-signed certificate using OpenSSL (run this in your macOS Terminal, Windows PowerShell, or Linux shell):

   Windows users: OpenSSL is not pre-installed on Windows. Install it via Git Bash (included with Git for Windows), Windows Subsystem for Linux (WSL), or download from Win32 OpenSSL.

   openssl req -new -x509 -days 365 -keyout jwt_key.pem -out jwt_cert.crt -nodes \
     -subj "/CN=datatrax-jwt"

   This creates two files:

   • jwt_cert.crt — certificate to upload to Salesforce (in this step)
   • jwt_key.pem — private key to provide to Datatrax (in Step 3)

Open External Client Apps in Setup

1. In Salesforce, click the gear icon → Setup.
2. In the Quick Find box, type External Client Apps and select it.
3. Click New External Client App.

Fill in the app details and save

Complete the form fields below exactly as shown, then click Create to save.

Configure OAuth Settings (Settings Tab)

Now configure the OAuth and JWT settings. These are all located under the Settings tab → OAuth Settings section.

Enable OAuth Settings

1. Click the Settings tab on your External Client App.
2. Scroll to OAuth Settings, expand and check Enable Oauth. OAuth settings will then appear.

Consumer Key and Consumer Secret

1. Click Consumer Key and Secret. You'll be prompted for an access code.
2. Enter the access code sent to your email and click Verify.
3. You'll see your Consumer Key and Consumer Secret. Copy both values to a notepad — you'll need them in Step 3 when connecting your org in the Datatrax portal.

Callback URL

1. Back in the OAuth Settings section, find the Callback URL field.
2. Enter:
   https://www.getdatatrax.com/auth/salesforce/callback

OAuth Scopes

1. In the Selected OAuth Scopes section, add these two scopes (use arrows or double-click to move them):
   • Manage user data via APIs (api)
   • Perform requests at any time (refresh_token, offline_access)

Flow Enablement and Certificate Upload

Enable both OAuth and JWT Bearer Flow, and upload your certificate:

1. Check Enable Authorization Code and Credentials Flow (required for OAuth).
2. Check Enable JWT Bearer Flow (required for per-user data loads). This will expose the Upload Certificate button.
3. Scroll to the Upload Certificate section.
4. Click Choose File and upload your jwt_cert.crt certificate file (the one you generated in the Prerequisites above).

Security

Configure these security settings:

1. Check Require secret for Web Server Flow.
2. Check Require secret for Refresh Token Flow.
3. Enable Refresh Token Rotation — this should already be checked. (Note: To change this required setting, contact Salesforce Support.)
4. Limit Idle Refresh Token Time-to-Live (TTL) to 30 days — this should already be checked. (Note: To change this required setting, contact Salesforce Support.)

Save and Activate

1. Click Save at the bottom of the page.
2. Wait 2–5 minutes for Salesforce to activate your External Client App with the new settings.
3. If you get an "invalid_client" error when connecting in Step 3, wait longer (up to 10 minutes) and try again.

Configure App Policies (Policies Tab)

To allow business users to submit data loads without requiring individual OAuth approvals, pre-authorize them via permission sets.

1. Click the Policies tab on your External Client App.
2. Scroll to OAuth Policies → Plugin Policies and set Permitted Users to Admin approved users are pre-authorized. (This setting must be configured first before the Permission Sets selection becomes available.)
3. Scroll to the Permission Sets section (now visible) and select both:
   • Datatrax User
   • Datatrax Admin
4. Click Save.

This pre-authorization means users in these permission sets can immediately use Datatrax without seeing an individual OAuth approval prompt.