Skip to main content

Setup Guide

This guide takes you from a freshly installed package to a verified connection. It follows the order of the aprity Setup Wizard in the aprity app. Follow the steps in order.

Before you begin​

  • A Salesforce org with API access (see Prerequisites).
  • System Administrator rights.
  • Your activation code.
  • The username and profile of the integration user (the Salesforce user aprity will connect as). Both are shown in Setup > Users.

Step 1: Install the package​

Open the installation link aprity sent you and install the package. See Installing the Managed Package for details.

Step 2: Assign the aprity Admin permission set​

  1. Go to Setup > Permission Sets.
  2. Open aprity Admin.
  3. Click Manage Assignments > Add Assignment.
  4. Assign it to your user and to the integration user.
Two things authorize the integration user

The aprity Admin permission set gives the integration user access to the aprity components. The profile you add to the External Client App in Step 6 pre-authorizes the connection. Both are required.

Step 3: Register your organization​

  1. Open the aprity app from the App Launcher. The aprity Setup Wizard opens.
  2. Enter your Activation Code and click Register.

aprity Setup Wizard - Registration screen

Once registered, the wizard shows Step 1: Download JWT Certificate and the instructions for the External Client App. More details: Registering Your Organization.

Step 4: Download the certificate​

In the wizard, click Download Certificate (.crt) and save the file.

Do this before you open the Salesforce form

Salesforce makes the certificate mandatory on the External Client App creation form. As soon as you check Enable JWT Bearer Flow, it asks for the file and refuses to create the app without it. Download it first, or you will have to abandon a half-filled form.

Step 5: Create the External Client App​

  1. In Setup, open External Client App Manager (the wizard has a direct link).

  2. Click New External Client App.

  3. Under Basic Information, fill in:

    • External Client App Name: aprity
    • API Name: aprity (filled in automatically)
    • Contact Email: contact@aprity.ai
    • Distribution State: Local (the default)

  4. Expand API (Enable OAuth Settings) and check Enable OAuth. The other OAuth fields only appear once this box is checked.

  5. In Callback URL, paste the URLs shown in the wizard, one per line. The wizard lists the exact URLs for the aprity environment your org is registered on. For the main aprity environment they are:

    https://login.salesforce.com/services/oauth2/callback
    https://api.aprity.ai/v1/portal/auth/sf/callback
    https://mcp.aprity.ai/v1/mcp/oauth/sf-callback

    The first line is required. The second is needed for the web portal sign-in, the third for AI clients (ChatGPT, Claude, Cursor, GitHub Copilot) connecting through the Remote MCP Server. Add all three now: a missing line shows up later as a Salesforce redirect_uri_mismatch page at sign-in.

  6. OAuth Scopes is a two-list picker. Select entries in Available OAuth Scopes and click ▶ to move them to Selected OAuth Scopes (Ctrl/Cmd-click selects several).

    Always required:

    • Manage user data via APIs (api)
    • Perform requests at any time (refresh_token, offline_access)

    Required for the web portal sign-in:

    • Access the identity URL service (id, profile, email, address, phone)
    • Access unique user identifiers (openid)
    Match the exact label text

    In External Client Apps, openid sits behind "Access unique user identifiers", not behind "Access the identity URL service". There is no separate "Access basic information (email)" entry: email and profile are part of the identity URL scope.

  7. Under Flow Enablement, check Enable JWT Bearer Flow. A Certificate Upload box appears: upload the .crt file from Step 4.

  8. Under Security, three boxes are checked by default: Require secret for Web Server Flow, Require secret for Refresh Token Flow and Require Proof Key for Code Exchange (PKCE).

    • If you use the web portal (recommended: it is where the documentation is published), uncheck Require secret for Web Server Flow and Require secret for Refresh Token Flow, and leave PKCE checked. The portal sign-in uses PKCE without a client secret; if a secret stays required, portal sign-in fails.
    • These boxes have no effect on the aprity connection itself, which uses the certificate.

  9. Click Create.

Create External Client App with JWT Bearer Flow enabled

Step 6: Configure the OAuth policies​

Required

Without these policies, the connection cannot be verified.

  1. In External Client App Manager, find aprity and open the row actions menu at the far right.

  2. Select Modify Policies.

  3. Expand OAuth Policies. Under Plugin Policies, set Permitted Users to Admin approved users are pre-authorized.

  4. Salesforce opens a Confirm permitted user policy dialog. Click OK.

    Order matters

    The Select Profiles picker only appears under App Policies once Permitted Users is set. Before that, App Policies only contains a Start Page field.

  5. Scroll back up to App Policies. In Select Profiles, move the integration user's profile from Available Profiles to Selected Profiles with ▶.

    Look up the profile, do not guess it

    Use the profile your integration user actually has, shown in Setup > Users. It is often a custom profile, not the standard System Administrator. A wrong profile is the most common cause of a failed verification, and the error does not name the missing profile.

    For the web portal, also add the profiles of the people who will sign in (for example Standard User). This alone does not give them access: the portal also requires the aprity User or aprity Admin permission set.

    Use profiles here, not the Select Permission Sets picker: the aprity permission sets can be refused on save because they belong to a managed package. Assign the permission sets directly to users instead.

  6. Under OAuth Policies > App Authorization, set IP Relaxation to Relax IP restrictions.

  7. Click Save.

External Client App Policies configuration

Step 7: Confirm in the wizard and enter the Consumer Key​

  1. Back in the aprity Setup Wizard, click I've Created the App and Uploaded the Certificate.
  2. The wizard shows Step 1.5: Enter Consumer Key. To find the key:
    1. In External Client App Manager, open the aprity app and go to its Settings (or use the row actions menu and select Modify Settings).
    2. Expand OAuth Settings. In the App Settings block, click Consumer Key and Secret.
    3. Salesforce may ask you to verify your identity with a code sent by email. Depending on your org's settings, this prompt may not appear; that is normal.
    4. Copy the Consumer Key.
  3. Paste it into the Consumer Key field of the wizard.
The Consumer Secret is not needed

aprity never uses the Consumer Secret. Copy the key only.

External Client App Settings - Consumer Key and Secret

Step 8: Configure and verify​

  1. In Step 2: Configure Salesforce JWT Bearer, enter the Salesforce Username of the integration user, exactly as shown in Setup > Users (for a sandbox it usually ends with the sandbox name).
  2. Click Configure & Verify. The login URL is detected automatically.
  3. If detection fails, the wizard asks for your MyDomain Login URL (for example https://mydomain.my.salesforce.com). Enter it and click Retry Verification.

When the connection works, the wizard shows Salesforce connection verified successfully! and the aprity app switches to its normal view, with the status Connected.

Verification Successful

If verification fails, see JWT Verification Fails.

You are connected​

The aprity app now shows its menu:

  • Analyses -- the list of your analyses and their status.
  • Web portal -- the link to your documentation portal.
  • New Analysis -- start an analysis (aprity Admin only).

Continue with Running Your First Analysis.