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 protected-resource metadata for each endpoint — /.well-known/oauth-protected-resource/gateway/mcp for the aggregate endpoint, /.well-known/oauth-protected-resource/gateway/mcp/{slug} for a single-MCP one — pointing the agent at your organization's issuer as the authorization server and advertising the mcp_gateway, profile, and email scopes. Each document's resource is the endpoint it describes, which a client following RFC 9728 checks against the URL it connected to before trusting the metadata.

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 points at the metadata URL for the endpoint that was called and repeats the 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 are custom agents: create one from the Custom agent card in the Agent Registry or Quickstart (Custom agent), choosing one of two credential types. A client that can self-register needs neither: it performs its own Dynamic Client Registration on first connect, exactly as a catalog agent does.

Custom agent credential types

• API key — the gateway mints an opaque bearer token, shown once, that you configure in the agent as a static header credential. Pick this for any client that just needs a token to send with every request.
• OAuth — for agents that authenticate over OAuth 2.0 (authorization_code) but can't self-register via Dynamic Client Registration and instead ask you to hand-paste an authorization URL, token URL, client ID, and client secret into their own settings. Pick this when the agent's own setup screen asks for those fields.

API key

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.

OAuth

When you choose OAuth, the gateway performs Dynamic Client Registration (RFC 7591) against your organization's own issuer on the agent's behalf — you don't register anything with the issuer yourself. The result is shown once, so copy it immediately:

• Client ID and Client Secret — the registered OAuth client's credentials. The secret is never stored by the gateway and can't be retrieved later.
• Authorization URL and Token URL — the issuer's endpoints for the agent's OAuth flow.
• Scopes — defaults to mcp_gateway profile email; leave it unless the agent needs something different.
• Redirect URI — the value you supplied when creating the instance (the agent's own fixed OAuth callback).
• MCP Server URL — the gateway endpoint to paste into the agent (see Gateway MCP endpoints above).
• Auth Method — the token-endpoint authentication method the issuer assigned (client_secret_basic or client_secret_post); set it in the agent if it asks how to send the client secret.

Once created, the agent authenticates through this client using the same OAuth flow described above — the gateway matches incoming JWTs to the instance by client ID, with no further setup on the gateway side. Deleting the instance also removes the registered client at the issuer.

Revoking access

Revoke access on an agent instance cuts off any JWT-based access: the gateway records the revocation time and rejects any JWT issued before it, so the agent must reauthenticate to get back in. This covers both agents registered through the browser flow and custom OAuth agents, since both present a JWT. A custom agent holding a static API key has no JWT to revoke and is cut off by deleting the instance instead, which invalidates the stored token 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.