Skip to main content

JWT Verification Fails

aprity uses JWT Bearer authentication to securely connect to your Salesforce org. If JWT verification fails, the scan cannot retrieve metadata. This guide walks through the most common causes and how to fix each one.

note

Salesforce now calls a Connected App an External Client App (ECA). Depending on your org's setup, the aprity app may appear under either name. The same External Client App also powers the web portal's OAuth single sign-on. The steps below apply to both.

Step-by-step diagnosis​

1. Certificate mismatch​

The certificate uploaded to the Salesforce Connected App does not match the private key aprity is using to sign the JWT.

How to verify:

  • In Salesforce, go to Setup > App Manager > aprity Connected App > Edit.
  • Under Use digital signatures, confirm the uploaded certificate file.
  • The certificate must be the exact .crt file that corresponds to the private key stored in your aprity configuration.

Solution:

  • Re-upload the correct certificate to the Connected App.
  • If you have regenerated certificates, update both sides: the certificate in Salesforce and the private key in aprity.

2. Consumer Key mismatch​

The Consumer Key configured in aprity does not match the one assigned to your Connected App.

How to verify:

  • In Salesforce, go to Setup > App Manager > aprity Connected App > View.
  • Copy the Consumer Key value.
  • In aprity, verify this matches the value stored during registration.

Solution:

  • Update the Consumer Key in your aprity JWT configuration to match the Salesforce Connected App.

3. Connected App not enabled for OAuth​

The Connected App exists but OAuth settings are not properly configured.

How to verify:

  • In Salesforce, go to Setup > App Manager > aprity Connected App > Edit.
  • Under OAuth Settings, confirm that Enable OAuth Settings is checked.
  • Confirm that the required OAuth scopes are selected (at minimum: api, refresh_token).

Solution:

  • Enable OAuth settings and add the required scopes.
  • Save the Connected App and wait 2-10 minutes for changes to propagate.
note

Salesforce can take up to 10 minutes to propagate Connected App changes. If you just made a change, wait and retry before further troubleshooting.

4. Digital signatures not enabled​

The Connected App is not configured to accept JWT Bearer token authentication.

How to verify:

  • In the Connected App settings, confirm that Use digital signatures is checked.

Solution:

  • Check the Use digital signatures checkbox and upload the certificate.

5. User not pre-authorized​

The Salesforce user account aprity connects as has not been pre-authorized for the app. This is the most common cause of a failed verification, and the error message does not name the missing profile -- so check it before anything else.

How to verify:

  1. Find the integration user's actual profile: Setup > Users, locate the username you entered in aprity, and read its Profile column.

    :::warning Do not assume the profile Most orgs run their integration user on a custom profile, not the standard System Administrator. The setup guide uses a generic example; your org almost certainly differs. Read the actual value rather than trusting the example -- a mismatch here produces exactly this failure. :::

  2. Open the app:

    • External Client App: open Setup > External Client App Manager, locate aprity, open its row actions menu, then select Modify Policies.
    • Legacy Connected App: Setup > Connected Apps > Manage Connected Apps > aprity.

  3. Confirm Permitted Users is Admin approved users are pre-authorized.

  4. Confirm the profile from step 1 appears verbatim in Selected Profiles (ECA) or the authorized profiles list (Connected App).

Solution:

Add that exact profile to the app's authorized profiles and save.

:::info Confirm the save took effect On an External Client App, return to External Client App Manager after saving, open the aprity row actions menu, and select Modify Policies again to confirm the profile is still listed in Selected Profiles. A save can report success while the profile assignment does not persist -- and the resulting failure looks identical to never having added it. :::

Note that on an External Client App the Select Profiles picker only appears once Permitted Users is set to Admin approved users are pre-authorized; if you do not see the picker, set that first.

6. Username or login URL incorrect​

The JWT assertion specifies the wrong username or targets the wrong Salesforce instance.

How to verify:

  • Confirm the username in aprity matches the full Salesforce username (e.g., admin@company.com or admin@company.com.sandbox).
  • For sandboxes, ensure the login URL is https://test.salesforce.com (not https://login.salesforce.com).

Solution:

  • Update the username and login URL in your aprity JWT configuration.
caution

Sandbox usernames include the sandbox name as a suffix (e.g., user@company.com.mysandbox). Using the production username for a sandbox will fail.

Verifying the fix​

After applying changes:

  1. Wait 2-10 minutes for Salesforce to propagate Connected App updates.
  2. In the aprity app, navigate to Settings > Connection and click Test Connection.
  3. If the test succeeds, run a scan to confirm full metadata access.

Still not working?​

Collect the following and send to support@aprity.ai:

  • The exact error message from the aprity app or scan log.
  • Your Salesforce Org ID (Setup > Company Information).
  • Whether you are connecting to a production org or sandbox.
  • The Connected App name and Consumer Key (not the Consumer Secret).