Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Version: 11.3.0

Creating a Service Agent

Overview​

You create a service agent on the Cloud 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, because together they are the whole boundary the credential works inside.

note

Creating a service agent needs a role that can manage service agents. Out of the box, only AgentPassAdmin can. See Service 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. See Controlling MCP Tool Access by Role. A role created for one service agent is often clearer than a reused person's role.
  • The connectors it will call. If they do not exist yet, add them first so you can select them.

Create the Service Agent​

  1. In the console, open Oversight → Cloud Agents.
  2. Click New agent, then choose New service agent.
  3. Complete the form. The fields are described in the following table.
  4. Click Create. AgentPass issues the credential and shows it once.

The form has these fields.

FieldWhat it does
NameHow the service 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 service agent is for, in plain language
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 service 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 service 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 service 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 dialog that opens after you create the service agent. It keeps only a one-way hash, 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.

Service agent credentials begin with hypr_sa_, which 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 service 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​

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

The Role​

The role on the credential is the service agent's authority. It decides which MCP tools the gateway offers the service agent and which calls it may make, just as a supervisor's role does 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 service agent the AgentPassAdmin 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 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 service 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 service 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 service agent acts as the owner. Anyone holding the credential can then 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, because there is no organizational credential to fall back to. The gateway refuses a service agent's calls there until you name the connector here, even though it is in scope.

For those connectors, leaving the setting off means no access, not reduced access. If a service 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, and the console flags the service agent as needing 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.

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 AgentPassAdminThat 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 Service Agent.