Gateway endpoints and authentication

SecureAuth Agent Authority exposes a small, fixed set of URLs. This page is the lookup reference for what each one does and how authentication works at each layer — agent to gateway, and gateway to upstream service.

Gateway MCP endpoints

Point an agent at the aggregate endpoint for the broadest access, or at a single-MCP endpoint to stay under an agent's tool-count cap — see Scope a connection to one MCP.

Both endpoints are filtered per caller before the agent ever sees them: a tool denied by policy is left out of the tool list rather than blocked at call time, so two users pointed at the same URL can see different tools. Tools from a resource whose discovery is currently failing are absent until it recovers.

Agent authentication

Agents connect over MCP and authenticate through the browser sign-in flow the agent surfaces on first connect (see any agent's setup guide, for example Claude Code). The gateway auto-registers the connecting client as a new agent instance and ties it to the user who completed sign-in — see Agent Registry for how instances are tracked afterward.

Under the hood that flow is standard OAuth. The gateway serves /.well-known/oauth-protected-resource, which points the agent at your organization's issuer as the authorization server and advertises the mcp_gateway, profile, and email scopes. The access token the agent presents must carry the mcp_gateway scope — a JWT without it is rejected with 403 missing required mcp_gateway scope, while a missing or unreadable token gets a 401 whose WWW-Authenticate header repeats the metadata URL and required scopes. Those two responses are the first thing to check when an agent won't connect.

Agents that can't run the browser flow authenticate with a static bearer token instead — the one shown once when you create an instance from Agent Instances → Create custom agent (Connect an agent). The gateway stores only a hash of the token and resolves each call to that instance and its user. Treat the token like a password: it's shown once and can't be retrieved later.

Revoking access

Revoke access on an agent instance cuts off tokens the browser flow already issued: the gateway records the revocation time and rejects any JWT issued before it, so the agent must sign in again to get back in. Revocation applies to instances registered through OAuth; a custom agent holding a static token is cut off by deleting the instance, which invalidates the stored hash.

Per-user authentication to upstream services

Once an agent is connected, each tool call still needs the right upstream credentials. For catalog resources the gateway never uses a shared service account: it calls the upstream MCP server with the requesting user's own connection. The first time a user's agent calls a tool that needs a connection they haven't made yet, the gateway returns a link prompting them to complete OAuth with that provider; every later call reuses the stored credentials automatically. Custom resources configured with API Key or OAuth2 client-credentials authentication are the exception: those use credentials set once on the resource and shared by every caller — see Security and data handling.

Which OAuth app starts that per-user flow — SecureAuth's own app, a per-organization dynamic client registration, or one your organization brings — is decided once per resource, at install time. See Credential modes for the full comparison.

Next steps

• Connect an agent — register your first agent instance.
• Credential modes — choose the OAuth app behind a resource.
• Connections — how per-user upstream authentication works day to day.