Salesforce users for integrations and agents — integration users, Run As users, agent users, permission sets, and assigning them from the CLI
Which Salesforce user each call runs as and what it needs — API-only integration users with the Salesforce Integration licence, the Run As user behind client credentials and the Agent API, the agent user that service agents run as (sf org create agent-user, Einstein Agent User profile, AgentforceServiceAgentBase, AgentforceServiceAgentUser, EinsteinGPTPromptTemplateUser), employee agents running as the signed-in user, and permission sets and groups as the way to grant access.
markdownreferencev1CHVE-5CG0stage: designtrust: officialservice: accessinterface: cliinterface: portalintegration userAPI only userSalesforce Integration user licenseSalesforce API Integration permission set licensefive free integration licensesMinimum Access - API Only IntegrationsRun As userclient credentials run asagent usersf org create agent-userEinstein Agent User profileAgentforceServiceAgentBaseAgentforceServiceAgentUserEinsteinGPTPromptTemplateUserdefault_agent_userAgent Script config blockemployee agent runs as userservice agent userpermission setpermission set groupsf org assign permsetsf org assign permsetlicense--on-behalf-ofleast privilege integrationAPI Enabled permission
Users for integrations and agents
Every Salesforce call runs as a user, and that user's permissions and sharing decide what the call can see and change. Pick the user deliberately for each path.
| Path | Runs as | Give it |
|---|---|---|
| Your backend with client credentials (including the Agent API) | The ECA's Run As (Username) | An API-only integration user with only the permission sets the job needs. The Agent API asks for at least API Only access |
| JWT bearer (CI, CLI) | The sub user in the assertion | Pre-authorized on the ECA by profile or permission set. A deploy user needs broad metadata permissions, so keep it out of runtime paths |
Service agent (customers on a website, messaging, the Agent API with bypassUser: true) | The agent's agent user | The agent user permission sets below, plus access to the objects its actions touch |
| Employee agent (in Salesforce, Slack) | The signed-in user | Their own permissions: an employee agent can only do what the user can |
Integration users
Salesforce offers an API-only Salesforce Integration user licence. It's paired with the Salesforce API Integration permission set licence, and Enterprise, Unlimited and Performance orgs get five free. These users have no UI access, so they can't serve anything that needs a browser login.
Field reports say the API-only profile is now "Minimum Access - API Only Integrations". The hub's reading: pick whichever API-only profile your org lists, and grant everything through permission sets.
Agent users
sf org create agent-user --target-org <alias> creates the default user an agent runs as:
- a user named "Agent User" with a globally unique username;
- the Einstein Agent User profile;
- the required permission sets AgentforceServiceAgentBase, AgentforceServiceAgentUser and EinsteinGPTPromptTemplateUser.
The command also checks that the licences are available. The user has no password and can't log in; only admins see it in Setup. Reference it in the agent's Agent Script as default_agent_user in the access block. Salesforce's CLI templates still put it in config, where it's deprecated (reference/agentforce/agent-script.md). Add access with sf org assign permset --name <permset> --on-behalf-of <agent-username> --target-org <alias>, and licences with sf org assign permsetlicense.
Permissions, the least-privilege way
- Permission sets and permission set groups grant access; profiles stay minimal. Deploy them as metadata (family 2) so every org gets the same grants.
- One integration user per integration, so Login History, event logs and Agent API traces show which system did what.
- Agents act with the agent user's access. The hub's reading: give its permission sets only the objects and fields its actions read or write, and keep the steward agent's write-back (the agent-force demo's "custom agent actions that write back") on a separate, narrowly scoped permission set.
Auth errors for these users: reference/auth/oauth-and-session-errors.md.