Log in Start free trial
Install Guide / Step 3

Configure Datatrax Settings

Connect your Salesforce org to your Datatrax account, then configure the org-wide settings.

Connect your Salesforce org

The first step authorizes Datatrax to write results back to your Salesforce org. This uses a secure OAuth connection — Datatrax never stores your Salesforce password.

  1. Log into your Datatrax portal and go to Settings.
  2. Under Salesforce Connection, click Connect production org or Connect sandbox org depending on your target environment.
  3. On the "Connect [Production/Sandbox] Org" screen, enter the Consumer Key and Consumer Secret from the External Client App you created in the previous step, then click Authorize with Salesforce →.
  4. You'll be redirected to Salesforce to authorize the Datatrax connection. Log in if prompted, then click Allow.
  5. After authorizing, you'll be returned to the Datatrax portal. Your org will show as connected.
Salesforce takes a few minutes to activate new External Client Apps. If you see an error like error=invalid_request&error_description=missing%20required%20code%20challenge, wait 5-10 minutes for Salesforce to fully activate the app, then try connecting again. This is normal and not an error with your setup.

Copy your HMAC Secret, Endpoint URL, and License Key

After successfully connecting your org, the Datatrax portal displays your credentials. You'll need these for the Salesforce configuration:

  1. Copy your HMAC Secret. Keep this private — anyone with this value can send authenticated requests to your Datatrax endpoint.
  2. Copy the Heroku Endpoint URL: https://www.getdatatrax.com
  3. On the Datatrax portal Settings page, copy your License Key (starts with dtx_).

Open Datatrax Settings in Salesforce

  1. In your Salesforce org, go to Setup.
  2. In the Quick Find box, type Custom Settings and click it.
  3. Find Datatrax Settings in the list and click Manage.
  4. Click New next to Default Organization Level Value to create the org-wide default.

Enter your credentials

  1. Paste your HMAC Secret into the HMAC Secret field.
  2. Enter https://www.getdatatrax.com into the Heroku Endpoint URL field.
  3. Paste your License Key into the License Key field.
  4. Click Save.
Keep your HMAC Secret private. Anyone with this value can send authenticated requests to your Datatrax endpoint. Treat it like a password — don't share it in Slack, email, or public repositories. Once you enter it into Salesforce Custom Settings, you can always retrieve it again from there if needed.

Verify the settings

In the Datatrax portal, go to Settings and check the Connected Salesforce Orgs table. Confirm the following for your org:

  • Name — Your org's name
  • Type — Production or Sandbox
  • Status — Connected (green indicator)
  • Org ID — Your 18-character Salesforce Org ID
  • License Key — Matches what you entered in Salesforce Custom Settings
Why is this required? When Datatrax finishes processing a data load, it writes the results — status, record counts, and error details — back to the Data Load Request record in your Salesforce org. The OAuth connection gives Datatrax the API access needed to do that.

Configure JWT Bearer Flow (Upload Private Key)

You've already generated a certificate and uploaded it in Step 2. Now provide the private key to Datatrax so it can authenticate data load requests as the submitting user.

What JWT Bearer Flow does

  • Audit compliance — each load is traceable to the user who initiated it
  • Row-level security — if a user can't access certain records, their loads can't either
  • Permission enforcement — users can only load data they'd be allowed to modify

Only users with the Run as Datatrax Integration User permission can bypass this and run data loads as a system integration user instead.

Step 1: Upload private key to Datatrax

  1. In the Datatrax portal, go to Settings.
  2. Find your org in Connected Salesforce Orgs and click the ⋮ menu.
  3. Click JWT credentials.
  4. Paste the contents of your jwt_key.pem file (the private key you generated in Step 2 Prerequisites) into the JWT Private Key field.
  5. Click Save JWT Credentials. Status badge should show "Configured".

Step 2: Verify the setup

  1. In the portal, check your org's JWT status badge shows "Configured".
  2. In Salesforce, submit a test data load (ensure your user doesn't have the Integration User permission).
  3. In portal → Jobs, click your test job and verify the log shows it ran as you (per-user mode).
Keep your private key safe. Never commit jwt_key.pem to source control or share it. Treat it like a password. Datatrax encrypts it on disk; the plaintext never displays for security.

Rotating credentials

To rotate your JWT certificate:

  1. Generate a new certificate and private key using the OpenSSL command from Step 2 Prerequisites.
  2. Upload the new certificate to Salesforce in Step 2 (Configure OAuth Settings → Flow Enablement and Certificate Upload).
  3. Update the private key in the Datatrax portal (Step 1 above).
  4. Wait 5 minutes for Salesforce to activate the new certificate.
  5. Delete the old certificate from Salesforce.

Troubleshooting Settings & Credentials

JWT Status Shows "Not Configured"

Cause: No JWT private key has been uploaded yet.

Solution: Follow Step 1 above to upload your private key to the portal.

JWT Status Shows "Invalid Key"

Cause: The private key is not a valid RSA key in PEM format.

Solution:

  • Ensure you're pasting the private key (starts with -----BEGIN RSA PRIVATE KEY-----), not the certificate.
  • If the key is lost, generate a new one and follow Steps 2-3 again.

JWT Private Key Disappears After Saving

Cause: This is normal! Private keys are encrypted at rest and never displayed in plaintext for security.

Solution: Check the JWT status badge — if it shows "Configured", your key is saved securely.

Connection succeeded but shows "Refresh Failed" status

Cause: OAuth token refresh failed (usually due to expired or invalid credentials).

Solution:

  1. Click your org → Reconnect to refresh the OAuth connection.
  2. Verify your Consumer Key and Secret are still valid in Salesforce (they may have been rotated).

Troubleshooting Data Loads with JWT

Data Load Fails: "grant type 'jwt-bearer' not supported"

Cause: The External Client App doesn't have JWT Bearer Flow enabled, or certificate wasn't uploaded correctly.

Solution:

  1. In Salesforce, verify Use digital signatures is checked on the External Client App.
  2. Verify the certificate file is uploaded (should show a filename).
  3. Wait 5 minutes and try the data load again.

Data Load Fails: "aud claim does not match endpoint"

Cause: Org type mismatch (sandbox vs production detected incorrectly).

Solution:

  1. In the portal, check your org's Type column (should be "Sandbox" or "Production").
  2. If wrong, disconnect and reconnect the org (it will auto-detect from instance URL).
  3. Try the data load again.

Data Load Fails: "jti claim has already been used"

Cause: Salesforce is rejecting a duplicate JWT (usually transient with retries).

Solution: Wait for the job to retry — it usually succeeds on the next attempt. If it persists, verify your system clock is synchronized.

Data Load Shows As "Processing" Forever

Cause: Background job may be stuck or failed silently.

Solution:

  1. Check Heroku logs for errors: heroku logs -t -a your-app-name
  2. If stuck for > 30 minutes, disconnect and reconnect the org to refresh credentials.
← Create an External Client App Next: Create a Mapping →