Skip to main content
Version: 11.5.0

Creating a Workload Agent

You create a workload agent on the Agents page of the HYPR AgentPass™ administration console. Creating one issues its credential.

Decide its role and the connectors it may reach before you start. Together they are the whole boundary the credential works inside.

note

Creating a workload agent needs Workload agents: Manage, which Admin has out of the box. See Workload Agents.

Before You Begin​

Have these ready:

  • The person who will own it. The accountable owner must already be a supervisor on your gateway, with a role assigned. See Roles and Permissions.

  • The role the credential should carry. On that role's Agent tools permission tab, grant only the tools this caller needs. A role created for one workload agent is often clearer than a reused person's role. See Controlling MCP Tool Access by Role.

  • The connectors it will call. If they do not exist yet, add them first so you can select them.

Create the Workload Agent​

  1. In the console, open Agents.
  2. Click New agent, then choose New workload agent. The New workload agent form opens.
  3. Complete the form. The fields are described in the following table.
  4. Click Create. AgentPass issues the credential and shows it once.
The New workload agent form, with the Runs setting, the accountable owner, the role, the connectors in scope and the expiry

The form has these fields.

FieldWhat it does
NameHow the workload agent appears in the console, the Request Log and its activity records. Use the name of the system that will hold the credential
DescriptionWhat the workload agent is for, in plain language
RunsOn a machine or In the cloud. Decides whether the Agents page lists it under Runs: Local or Runs: Cloud. When the page's Runs filter is set, the form starts with that choice. Otherwise, choose one
Accountable ownerThe email address of the person accountable for the credential. Must be an existing supervisor with a role
RoleThe role the credential acts with. This role, not the owner's, decides which tools it may call
Connectors in scopeThe connectors the workload agent may reach. Calls to any other connector are refused
ExpiresOptional. A date and time after which the credential stops working. The form fills in 90 days from now. Clear the field for a credential that never expires
May act as the owner onConnectors where the workload agent may use the owner's connected account. Leave it empty unless the agent must act as the owner. See Acting as the owner
Retain request payloadsWhether AgentPass retains this workload agent's request and response bodies. Off by default, because machine callers can be high-volume

Copy the Credential​

AgentPass shows the credential once, in the Workload agent created dialog. AgentPass keeps only a hash of it, so nobody can display or recover the credential later, including your HYPR representative.

Copy it straight into wherever the calling system keeps its secrets. If you lose it, rotate the credential to issue a replacement.

Workload agent credentials begin with hypr_sa_. That makes them easy to recognize in a configuration file or a secrets store.

Treat the credential like a password

Anyone holding it can make the calls this workload agent is permitted to make, from anywhere. Store it in a secrets manager, never in source control, a shared document or a ticket.

Choosing the Boundary​

Two settings define what the credential can do: the role and the connectors in scope. Two optional settings adjust it: acting as the owner, and expiry.

A workload agent's credential is checked against its boundary: the role decides which tools it may call, the connectors in scope decide where the credential is accepted, and two optional settings add the owner's account on named connectors and an expiry. A call inside the boundary goes on; a call outside it is refused. The accountable owner answers for the credential but is not a source of access.

The Role​

The role on the credential is the workload agent's authority. It decides which MCP tools the gateway offers the workload agent, and which calls it may make. A supervisor's role does the same for a supervised agent.

Grant the narrowest role that works. If a credential leaks, a role holding only this caller's tools limits the damage to the work it was issued for.

You cannot give a workload agent the Admin role. That role reaches every tool without a per-tool check, so a credential carrying it would have no meaningful boundary. AgentPass refuses the assignment.

Connectors in Scope​

The connectors in scope bound where the credential works. The gateway matches each call's connector exactly against the names on the credential. It refuses a call to any connector outside the scope, whatever the role permits.

Name only the connectors the caller uses. Scope is checked on every request, so narrowing it later takes effect immediately.

A workload agent with an empty scope reaches nothing, so AgentPass asks for at least one connector.

Acting as the Owner​

Some connectors reach a third-party service through an account a person has connected to the gateway, such as the owner's Jira or Slack account. A workload agent uses those accounts only on connectors you name under May act as the owner on.

Leave this empty unless a connector requires it. On a connector you name here, the workload agent acts as the owner:

  • Anyone holding the credential can act as that person on that connector, for as long as the credential is valid.

  • You can select only connectors already in the credential's scope.

Some connectors need this to work at all

Some MCP server connectors are set to OAuth (Managed by Gateway), where AgentPass manages each person's OAuth tokens. On those connectors, every call uses somebody's connected account. There is no organizational credential to fall back to.

The gateway refuses a workload agent's calls there until you name the connector here, even though it is in scope. Leaving the setting off means no access, not reduced access. If a workload agent is refused on one and its scope looks right, check this setting.

Expiry​

The form fills in Expires with a date 90 days from now. If you clear the field, the credential never expires. That is a legitimate choice for a long-running integration, but make it deliberately.

Set an expiry when the work has a natural end, such as a migration, a pilot or a proof of concept.

The gateway refuses an expired credential on its next call. The Agents page then shows it as Credential expired, under Needs attention, so it does not fail silently.

What AgentPass Refuses at Creation​

AgentPass declines to issue a weak credential, and tells you what to fix. It refuses in these cases.

AgentPass refuses whenWhy
The owner is not a supervisor with a roleAccountability has to point at a real person on your gateway
The role does not existA credential with no valid role would be refused on every call
The role is AdminThat role has no per-tool boundary. See The role
No connector is in scopeThe credential could reach nothing
A connector under May act as the owner on is not in scopeThe opt-in has to sit inside the boundary, not outside it
The expiry is in the pastThe credential would be refused immediately

Next Steps​

Configure the credential in the calling system, and confirm its first call. See Connecting a Workload Agent.