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

Quick Start: Administering HYPR AgentPass

This page takes you from your first sign-in to the HYPR AgentPass™ console to running it day to day. Work through the setup sections in order. The sections after them are for reference once agents are live.

What you'll need
  • The gateway's public origin, reachable from outside your network
  • An identity provider that supports OpenID Connect (OIDC), where you can register an application
  • Your HYPR tenant, with Control Center admin access
  • An account with each AI provider or service you plan to connect

What AgentPass Governs​

AgentPass is a gateway between your organization's AI agents and the models, tools and systems they reach. It attributes each request to an agent and a person, and checks it against your policies. A policy can block the request or hold it for a person's approval. AgentPass also limits each agent to the MCP tools its supervisor's role allows, and records what happened.

It governs these kinds of agent.

Kind of agentExamplesHow its traffic reaches the gateway
Local, on a person's workstationClaude Code, Codex CLI, CursorThe agent points at the gateway, or Endpoint Guard routes it there
Cloud, hosted by a providerMicrosoft 365 Copilot, Anthropic managed agents, AWS Bedrock AgentCoreA connector. People reach them in the Agent Portal or Slack
Service, with nobody at the keyboardAutomations and pipelinesA credential the gateway issues

As the administrator, you connect the tools your organization uses, decide who can do what, and keep policies, approvals and records working.

Before You Start​

Settle the gateway's public origin first, because your identity provider, connectors and agents are configured against it. The console is served from that origin at /admin/ui/, and the Agent Portal at /portal/.

For mobile approvals, create an application for the gateway in HYPR Control Center. Turn on FIDO2 for it, and generate an API access token scoped to it. Control Center shows the token only once.

Decide Who Gets Which Role​

Every person who signs in holds a role. AgentPass provides three system roles.

RoleWhat it can doGive it to
AgentPassAdminEverything, including settings, connectors, roles, data management and offboarding. Locked, so it can't be editedThe people who set up and change AgentPass
AgentPassOperatorReads everything. Turns any agent off and on, decides approvals, adds agents and writes its own policies. Can't change settings, connectors or rolesThe people who run AgentPass day to day
AgentPassSupervisorManages the person's own agents, approvals, conversations and policies. The default for anyone with no mapped roleEach person who owns an agent

Sign In and Connect Your Identity Provider​

Your first sign-in uses the recovery administrator, a break-glass account held by the gateway. Its credentials come from the invitation that set up your tenant.

  1. Sign in to the console as the recovery administrator.
  2. Open Advanced → Gateway Settings, and click the Authentication tab.
  3. Under Console SSO (OIDC), copy the Redirect URI, and register it with your identity provider.
  4. Enter the Issuer / auth-server URL. AgentPass reads your provider's endpoints from it.
  5. Enter the Client ID. If your application has a client secret, enter it in Client secret, and click Save secret.
  6. Set the claims described in the following table.
  7. Click Save settings.
  8. Turn on Enable SSO. AgentPass checks your provider before it turns SSO on.
  9. Sign out, and sign back in with single sign-on (SSO) to confirm it works.
ClaimSet it to
Principal claimA unique, stable value per person, such as an employee ID or sub
Display name claimsThe claims that make up the name shown in the console
Email claimThe claim that holds the email address
Role claimThe claim that carries each person's roles or groups, such as groups
The Console SSO settings, with the redirect URI, issuer and client credential fields to complete

Once SSO works, keep the recovery administrator credentials in a protected break-glass location.

Choose the principal claim before you roll out

Changing the principal claim later strands the role assignments keyed to the old identifier.

Map Roles From Your Identity Provider​

Grant roles from your directory groups, so AgentPass access follows your existing joiner, mover and leaver process.

  1. Open Oversight → People, and click the Roles tab.
  2. Click Edit on a role, or View on AgentPassAdmin.
  3. Under Identity provider, add each claim value that grants the role, such as a group name.
  4. Click Save in that section.
  5. Repeat for each role.

Matching is exact and case-sensitive. A person whose values map to no role gets AgentPassSupervisor.

For a one-off exception, open the person's actions menu (⋮) on the Humans tab, and choose Change role. That role replaces the roles from sign-in until you click Use identity provider roles in the person's details.

Connect the Tools Your Organization Uses​

A connector brings one target under the gateway: an AI provider, an MCP server, a REST API, a cloud agent or a chat channel. Set up the target's side first, because the form asks for its values.

  1. In the console, click Add Connector.
  2. Click the kind of connector, then the target's card, such as Anthropic.
  3. Complete the form, and click Create Connector.
The Add connector page, listing the connector kinds to choose from

The following table lists what common targets ask for.

TargetHave ready
Anthropic or OpenAIA provider account. An admin API key lets the gateway sync agent identities. OpenAI also needs the project ID
AWS BedrockThe AWS account and region, and two IAM policies in that account
MCP serverThe server's URL and how it authenticates. The connector then gives agents a gateway address for the server
Microsoft 365 CopilotAn Entra tenant with Copilot licenses, and two Entra app registrations. Consent needs Global Administrator, or Application Administrator plus Cloud Application Administrator
Slack AgentA Slack workspace where you can install an app, the app's signing secret and bot token, and a cloud agent to answer

The Microsoft 365 Copilot connector also runs the Agent Portal, where employees chat with Copilot and your Copilot Studio agents. Once its portal sign-in details are set, its Overview tab shows the Portal URL to send your users.

Choose How New Agents Are Onboarded​

An AI provider connector's onboarding mode decides what happens to a new agent's first request. You choose it on the form's last step, and can change it on the connector's Overview tab.

ModeWhat happens to a new agent's first request
Require ApprovalHeld until the agent's supervisor approves it
Observe onlyRecorded and forwarded. Nothing is blocked or onboarded
Auto ApproveHeld until the agent's supervisor approves it, as with Require Approval. Not available for AWS Bedrock or AWS Bedrock Mantle
DisabledNot held or onboarded

AWS Bedrock and AWS Bedrock Mantle offer only Observe only, Disabled and, with identity enrichment, Require Approval. Identity enrichment is an IAM role or an access key on the connector.

Start a workstation rollout in Observe only to see what's running, then move to Require Approval. How long a held request waits, and how long an approval lasts, are set under Advanced → Gateway Settings → Approvals.

Limit Which Tools Each Role Can Use​

New MCP tools arrive with no access. An agent is offered only the tools its supervisor's role may call.

  1. On the Roles tab of Oversight → People, click Edit on the role.
  2. Go to Agent tools permission.
  3. Expand a connector, and select each tool the role needs.
  4. Click Save changes. The change applies on each agent's next request.
The tool permission grid for a role, with one section per connector to expand and select tools in

AgentPassAdmin always has every tool. Review this tab whenever you add a connector, or an MCP server gains tools.

Set Up Approvals on Phones​

Supervisors approve held requests in the HYPR app, with a passkey. Connect the gateway to your HYPR tenant, then turn on push delivery.

  1. Open Advanced → Gateway Settings, and click the Passkeys (FIDO2) tab.
  2. Under HYPR FIDO2 Integration, enter your HYPR tenant base URL, the RP API access token, the RP Application ID and the gateway public origin. Click Save beside each.
  3. When all four are set, the card reads Ready. Click Check connection to confirm the gateway reaches your tenant.
  4. Under Mobile App Associations, enter the HYPR app identifiers your HYPR representative gives you.
  5. Under Passkey approval policy, enter the HYPR Mobile AAGUIDs your HYPR representative gives you in HYPR Mobile AAGUIDs.
  6. Open Advanced → Notifications.
  7. In the Firebase Cloud Messaging card, turn on Enable Firebase channel, enter the Project ID, and paste the Service Account JSON.
  8. Click Save FCM settings.

Then invite each supervisor to enroll a passkey. On the Humans tab of Oversight → People, open the person's actions menu (⋮), and choose Send invite (or Send reminder) or Copy invite link. The supervisor installs the HYPR app, signs in, and enrolls from My Passkeys. Under Test Push on Advanced → Notifications, send them a test, and confirm their phone receives it.

Decide When Approvals Must Be Signed​

Require signed approvals, on the Passkeys (FIDO2) tab, decides whether each approval must carry the supervisor's passkey signature.

SettingEffectUse it
Optional (soak)An approval without a passkey is recorded, and flagged as unsignedWhile supervisors enroll. A new organization starts here
Required (production)Approve works only with an enrolled passkeyOnce every supervisor is enrolled

Passkey approval policy, on the same tab, decides which passkeys count. Strict (HYPR Mobile only) accepts only passkeys enrolled from the HYPR app. This is the default. Until HYPR Mobile AAGUIDs has an entry, no passkey can approve.

Bring Agents Under the Gateway​

Each agent gets an identity with an owner, so every request is attributed to an agent and a person.

  • Local agents. The agent's provider base URL is set to the gateway's public origin, such as ANTHROPIC_BASE_URL for Claude Code. To route workstations centrally, use Endpoint Guard. Under Oversight → Discovered → Agent Observability, create an enrollment token, turn on Enable agent observability, and deploy the endpoint client with the token. Then turn on managed mode, and select the tools, under Oversight → Desktop Tools. On Windows, Endpoint Guard routes tools, provisions MCP and blocks egress for the whole device. Hooks, channels and Claude Desktop are macOS-only.
  • Cloud agents. Anthropic and AWS Bedrock AgentCore agents appear under Oversight → Cloud Agents. On each agent's Assignments tab, choose who may use it. Copilot Studio agents are added on the Microsoft 365 Copilot connector's Copilot Studio agents tab.
  • Provider keys. On Oversight → Agent identities, choose a connector under Import from, and click Sync Now. Each key becomes an identity, owned by the person it belongs to.
The Agent identities page, listing each agent with its owner, scopes, Active switch and Mobile access switch

With Require Approval, a new agent's first request waits under Needs your attention on Oversight → Approvals, and on its supervisor's phone. Approving it onboards the agent.

A pending onboarding request, with the connector, the time remaining, the agent and the Approve and Deny buttons

Roll Out Policies the Safe Way​

A policy pairs a condition with an action: allow, block, or require approval. A new policy starts in Observe mode by default. It records what it would have done, and changes nothing until you promote it.

To write a policy:

  1. Open Oversight → Policies.
  2. Click Add Policy to write the condition yourself. Author with AI drafts one from a plain-English goal, once a drafting model is set under Advanced → Gateway Settings → Policy Authoring.
  3. Choose the Action, and leave Mode at OBSERVE.
  4. Under Connectors, pick the connectors it applies to. Leave it empty for all.
  5. Click Create.

To check and promote it:

  1. Open the connector, and click its Policies tab.
  2. Filter the decisions to your policy, and read the Would block rows. Confirm it catches what you meant, and nothing else.
  3. On the policy's row, open the Mode dropdown, and choose ENFORCE.
  4. Click Set ENFORCE. The action applies from the next matching request.
The confirmation for changing a policy from Observe to Enforce, with the tip to check Observe events first

To roll back, choose OBSERVE in the same dropdown. Narrow the rule while it observes, then promote it again.

In the Agent Portal, chats and file uploads have no approval step. A matching Require approval rule blocks the message there, and shows the rule's message.

Check who can approve before you enforce

A Require approval policy needs a supervisor to answer. A request from a service agent has no supervisor, so it doesn't complete.

To find gaps, open the Coverage tab on Oversight → Policies. It shows which connector and tool pairs no rule reaches.

Run AgentPass Day to Day​

These pages cover routine operation.

PageUse it to
Activity DashboardSee connectors, cloud agents, policy blocks and approval outcomes at a glance
Oversight → ApprovalsAnswer, revoke and review approval requests
Oversight → Request LogFind any request from the last seven days, filtered by supervisor or type
Oversight → Access reviewsHave named reviewers confirm each agent still needs its access
Advanced → Data ManagementDecide where AgentPass's records go, and in what form

Approvals​

Supervisors answer requests for their own agents. AgentPassAdmin and AgentPassOperator can deny any request, and approve another supervisor's onboarding request. A request with no answer before its timeout expires, and an expired request isn't an approval.

To withdraw an agent's standing access, find its approved onboarding request under Resolved requests, and click Revoke. The agent must onboard again.

Access Reviews​

Schedule reviews, so access is confirmed regularly.

  1. Open Oversight → Access reviews, click Manage reviews, and click Schedules.
  2. On the Production agents card, turn on Review automatically.
  3. Set how often reviews open, and how long reviewers have. The defaults are every 90 days, with 14 days to finish.
  4. Name the Reviewers, and optionally a Fallback reviewer.
  5. Click Save. The first review opens within the hour.
The access review Schedules tab, with one card per agent stage to turn on and complete

Nobody reviews an agent they own, and a reviewer's removal takes effect straight away. Before an audit, click Open a review now on the Reviews tab.

Records and the Forensics Store​

AgentPass records each request, each policy decision and each administrative change. Advanced → Data Management shows where those records go.

DestinationWhat it isBy default
DatabaseThe store behind the Request LogAlways on
Export filesFiles on each gateway node, for your own compliance or analytics systemsOff
Log streamOne line per event in the gateway's logsOff
Forensics StoreLong-term storage, when your deployment has one connectedReceives every category

Export files and the log stream hash personal details, and leave out request and response content, unless you change that. The platform sets how long the database keeps records: 30 days for activity, 90 days for policy decisions, and indefinitely for the audit trail. By default, AgentPassOperator can read this page, and only AgentPassAdmin can change it.

The Data Management page, with the Database, Export files, Log stream and Forensics Store destinations above the event categories

Respond to an Incident​

Turn an agent off when it must stop now. It's reversible, and AgentPass records who did it and when.

To turn off a cloud agent or service agent:

  1. Open Oversight → Cloud Agents.
  2. Turn off the agent's Enabled switch.
  3. Optional: Enter a Reason. AgentPass records it with your name.
  4. Click Turn off.
The Turn off dialog for a cloud agent, with an optional reason entered

For a local agent, turn off its Active switch on Oversight → Agent identities. For a Copilot Studio agent, click Disable on its row in the Microsoft 365 Copilot connector's Copilot Studio agents tab.

The gateway refuses the agent's next request, and messages to it are refused. A cloud agent's running sessions at the provider end, and so do its automation runs in progress. To stop all traffic to one target, turn off the connector's switch on its Overview tab.

What turning off doesn't stop

A request already in progress finishes. On a connector in Observe only mode, except AWS Bedrock, a turned-off local agent's traffic is still forwarded. To keep a workstation tool from reaching its provider directly, turn on the tool's switch in the Egress enforcement card under Oversight → Desktop Tools.

Who Can Turn an Agent Back On​

One rule applies in the console and in the HYPR app.

Your role reachesYou can turn offYou can turn back on
All agents, as AgentPassAdmin and AgentPassOperator doAny agentAny agent
Only your own agents, as AgentPassSupervisor doesAn agent you ownOnly an agent you turned off yourself

So an agent an administrator turns off stays off until an administrator or operator turns it back on. Signing in again doesn't turn it on.

Offboard a Person​

Offboard someone who leaves, or who must lose access now.

  1. Open Oversight → People, and click the Humans tab.
  2. Open the person's actions menu (⋮), and choose Offboard.
  3. Read what the dialog says will be affected.
  4. Click Offboard.
The Offboard dialog for a supervisor, counting the agents, credentials, group memberships and approvals it affects

Their session ends, and their agent access, tool connections, roles and group memberships are removed. They can't sign in until someone invites them again, and their audit trail is kept. Deprovisioning them in your directory over SCIM has the same effect.

The dialog counts the pending approvals left unassigned. Deny any that no longer apply on Oversight → Approvals.

Service agents keep running

A service agent uses its own credential, so it keeps working after its owner is offboarded. Reassign or turn off each service agent the person owned.

To decommission an agent, open it under Oversight → Cloud Agents, click Change stage, choose Retired, enter a Reason, and click Change stage. A retired agent is switched off, and access reviews skip it.

What to Tell Your Users​

Point your employees to the two guides written for them, End User Guide: Using AI Tools with HYPR AgentPass and Quick Start: Using AI Tools with HYPR AgentPass. Then send each group what it needs.

  • Agent Portal users: the Portal URL. They sign in with their Microsoft work account, and need no console role.
  • People running local agents: the gateway's public origin, unless Endpoint Guard routes their tools.
  • Supervisors: a passkey invitation, and a note that approval requests arrive in the HYPR app.
  • Everyone: who to contact when AgentPass blocks a message, holds a request or turns an agent off.

Troubleshooting​

SymptomWhat to check
The identity provider refuses SSO sign-inThe registered redirect URI matches the console's Redirect URI exactly, and the provider permits the requested scopes
Someone gets AgentPassSupervisor instead of their mapped roleThe claim value matches the mapping exactly, including capitalization, and Role claim names the right claim
A supervisor gets no approval on their phonePush delivery is on, the test push reaches their device, and they haven't muted approval requests
Approve is unavailableSigned approvals are Required (production), and the approver hasn't enrolled a passkey
An agent can't see an MCP toolThe tool is selected under Agent tools permission on the supervisor's role
A new agent's requests pass without approvalThe connector's onboarding mode is Require Approval
Offboard is refused for your own accountAnother administrator must offboard you