Log in Start free trial
Install Guide / Advanced

JWT Bearer Flow Setup

Datatrax uses JWT Bearer Flow by default to run data loads as the submitting user's Salesforce identity. This guide explains how to generate and configure the JWT certificate required for this authentication method. JWT enforces user-level permissions and provides per-user audit trails.

Per-organization configuration. Each Salesforce org connects with its own JWT credentials. You'll provide your org's private key and certificate during the connection setup in the Datatrax portal.

What JWT Bearer Flow does

By default, Datatrax uses OAuth refresh tokens to authenticate to Salesforce. This means all API calls run under the identity of the user who authorized the connection.

JWT Bearer Flow lets each data load run as the user who submitted the request, not the user who authorized the connection. This is useful for:

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

Prerequisites

  • Your External Client App already created in your Salesforce org (see Step 2 of the Install Guide)
  • A private key and certificate for your org (you'll generate these below)
  • Access to the Datatrax portal Settings page

Step 1: Generate a certificate and private key

You need a self-signed certificate and private key. If you don't have these already, generate them using 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 — the certificate you'll upload to Salesforce
  • jwt_key.pem — the private key you'll store in Rails credentials

Keep jwt_key.pem private and secure. Anyone with this file can mint access tokens for users in your Salesforce org.

Step 2: Upload the certificate to Salesforce

  1. In your Salesforce org, go to Setup → External Client Apps.
  2. Find the Datatrax app and click it.
  3. Click Edit.
  4. Scroll to the Security section and check Use digital signatures.
  5. Click Choose File and upload the jwt_cert.crt file you generated.
  6. Click Save.
  7. Wait 2–5 minutes for Salesforce to activate the changes.

Step 3: Provide the private key to Datatrax

When you connect your Salesforce org in the Datatrax portal, you'll have the option to enable JWT Bearer Flow. At that point, you'll paste your private key into Datatrax, which encrypts it in the database per-org.

  1. Log into the Datatrax portal and go to Settings.
  2. Under Salesforce Connections, click on your connected org or Connect a new org if you haven't already.
  3. After entering your Consumer Key and Consumer Secret, look for the JWT Bearer Flow section (or a similar toggle).
  4. If you want to enable per-user data loads, check the box and paste the contents of your jwt_key.pem file into the private key field.
  5. Click Save. Your private key is encrypted and stored securely in the database, associated with your org only.
Keep your private key safe. Never commit jwt_key.pem to source control or share it via email/Slack. The credentials file is already encrypted on disk. Treat the private key like a password.

Step 4: Verify the setup

To verify JWT is configured correctly:

  1. In the Datatrax portal, go to Settings and check your org's connection status. Look for a JWT Configured indicator (or similar badge showing JWT is active).
  2. In Salesforce, enable per-user mode for a test load:
    • Create a Data Load Request
    • Ensure the Flow doesn't override Run Mode to Integration User
    • Submit the request
  3. After submission, go to the Datatrax portal → Jobs and click on your test job. The job log should show it ran in "Per-User" mode.

If the job fails with errors like External client app is not installed in this org, check that:

  • The certificate was uploaded to your External Client App in Salesforce
  • The private key you provided to Datatrax matches the certificate
  • At least 5 minutes have passed since uploading the certificate to Salesforce

Rotating credentials

To rotate the JWT certificate and private key for your org:

  1. Generate a new certificate and private key using the command in Step 1.
  2. Upload the new certificate to Salesforce (External Client App → Edit → Security).
  3. In the Datatrax portal Settings, find your org and update the JWT private key field with the new private key.
  4. Click Save.
  5. Wait 5 minutes for Salesforce to activate the new certificate.
  6. The old certificate can be deleted from Salesforce after activation.
Rotation takes effect immediately. Once you save the new private key in the Datatrax portal, subsequent data load jobs will use the new key without any app restart.

Troubleshooting

Error: "External client app is not installed in this org"

The JWT assertion is using a Consumer Key that Salesforce doesn't recognize.

  • Double-check the Consumer Key in your Rails credentials matches Setup → External Client Apps → Datatrax → Consumer Key and Secret.
  • Wait another 5–10 minutes and retry — new certificates can take up to 10 minutes to activate.

Error: "grant type not supported"

Salesforce is rejecting the JWT assertion itself.

  • Verify the certificate was uploaded to the External Client App and Use digital signatures is checked.
  • Ensure the private key in credentials matches the certificate uploaded to Salesforce.
  • Check that the Consumer Key (iss claim) and username (sub claim) in the JWT are correct.

Error: "jti claim has already been used"

Salesforce is rejecting a duplicate JWT. This can happen if retries fire too quickly.

  • This is usually transient. Check that the job eventually succeeds on a later retry.
  • If it persists, ensure your system clock is synchronized accurately — JWT tokens are time-sensitive.
← Controlling Access