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.
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
- In the console, open Oversight → Cloud Agents.
- Click New agent, then choose New service agent.
- Complete the form. The fields are described in the following table.
- Click Create. AgentPass issues the credential and shows it once.
The form has these fields.
| Field | What it does |
|---|---|
| Name | How 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 |
| Description | What the service agent is for, in plain language |
| Accountable owner | The email address of the person accountable for the credential. Must be an existing supervisor with a role |
| Role | The role the credential acts with. This role, not the owner's, decides which tools it may call |
| Connectors in scope | The connectors the service agent may reach. Calls to any other connector are refused |
| Expires | Optional. 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 on | Connectors 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 payloads | Whether 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.
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 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 when | Why |
|---|---|
| The owner is not a supervisor with a role | Accountability has to point at a real person on your gateway |
| The role does not exist | A credential with no valid role would be refused on every call |
| The role is AgentPassAdmin | That role has no per-tool boundary. See The role |
| No connector is in scope | The credential could reach nothing |
| A connector under May act as the owner on is not in scope | The opt-in has to sit inside the boundary, not outside it |
| The expiry is in the past | The credential would be refused immediately |
Next Steps
Configure the credential in the calling system, and confirm its first call. See Connecting a Service Agent.
Related
- Service Agents — what a service agent is and when to use one
- Connecting a Service Agent — present the credential and verify it works
- Managing Service Agent Credentials — rotate, disable and expire