---
url: https://veles.beyondthecloud.dev/docs/setup/integration-user.md
description: >-
  Who Veles signs in as, which permission sets exist, how to pre-authorise the
  External Client App, and what each verification message means.
---

# Integration user and ECA

Veles never asks you to log in to another org. It signs in on its own, as an **integration user**, with a short-lived JWT accepted by the **Veles External Client App (ECA)** that ships in the package. Step 1 of the Setup tab prepares that user. Every org that runs Veles, Hub or child, needs it.

## The integration user

A normal Salesforce user in the org. Recommended: a dedicated user whose only Veles permission set is **Veles Integration**, on a profile with **API Enabled**, **Modify Metadata Through Metadata API Functions**, **Manage Sandboxes** and **Manage Users**. If the user also holds **Veles Admin**, verification passes with a warning that says so.

In a sandbox the integration user is the production user's sandbox copy, so its username carries the sandbox suffix: `veles-integration@yourcompany.com.uat`. The Hub derives that name for you from the production username and the **Sandbox Name**; set **Integration Username** on the sandbox's environment row only to override it.

## Permission sets

| Permission set            | Who holds it                                  | Why                                                                                                                                                   |
| ------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Veles Admin**           | Every person who uses the Command Center      | Grants the app and its Apex classes. Auto-assigned to the installer.                                                                                  |
| **Veles Hub Integration** | Nobody. It is the template.                   | Least privilege: the Veles API class and nothing else. Clone it.                                                                                      |
| **Veles Integration**     | The integration user                          | Your unmanaged clone of the template. The ECA can only pre-authorise unmanaged sets. `sf veles setup` creates it on a scratch org or sandbox for you. |
| **Veles Developer**       | Whoever runs `sf veles setup` against the Hub | The custom permission the CLI plugin needs. **Veles Admin** includes it.                                                                              |

## Pre-authorising the ECA

**Setup > External Client App Manager > Veles > Policies > Edit.** Expand **OAuth Policies**, set **Permitted Users** to **Admin approved users are pre-authorized** and save. A **Permission Sets** section appears; click **Manage Permission Sets**, add **Veles Integration**, save.

Veles checks that at least one permission set is allowed on the ECA. It does not check which one, so make sure it is **Veles Integration**, the set the integration user holds.

## Verify Configuration

**Verify Configuration** (later **Re-Verify**) saves the username, then mints a token for this org as that user, exactly as a real call would. On success the box reads **Verified · Saved** with the granted scope.

| Message                                                                            | Fix                                                                                                        |
| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `User "<name>" not found or inactive.`                                             | Check the username, including the sandbox suffix, and that the user is active. Step 1.1.                   |
| `Unmanaged "Veles Integration" permission set not found`                           | Clone **Veles Hub Integration** and name the clone **Veles Integration**. Step 1.2.                        |
| `Assign the unmanaged "Veles Integration" permission set to the integration user.` | Step 1.3.                                                                                                  |
| `No permission sets allowed on Veles`                                              | Pre-authorise the ECA as above. Step 1.4.                                                                  |
| `user is not admin approved to access this app`                                    | Same as above: the user's permission set is not in the ECA's list.                                         |
| `External client app is not installed in this org`                                 | Despite the wording, the usual cause is a wrong or inactive username. Check Step 1.1 before anything else. |
| `Veles ECA not found in this org.`                                                 | The package install is incomplete. Reinstall or upgrade.                                                   |

Steps 2 and 3 stay locked until 1.2 and 1.4 pass.

## Licence coverage

The **Veles licence coverage** row under Step 1 is information only. A sandbox or scratch org reads **Covered by your Hub org**; a production org without its own licence tells you so and asks you to contact us, because every production org, including a sub-hub, is licensed on its own. See [Plans and pricing](/pricing).