Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Agent authentication discovery (auth.md)

Any MCP server you publish on FlowCP can advertise how an AI agent can authenticate to it using auth.md — an open protocol that lets agents discover a service's authentication flows on behalf of a user. Discovery is built entirely on the OAuth standards FlowCP already implements.

Agent auth is opt-in per server and off by default, in keeping with FlowCP's default-deny model. Turn it on from the server's Publish page with the Agent Auth (auth.md) toggle. While it is off, FlowCP publishes no auth.md document and emits no agent_auth block — discovery stays silent.

Enabling agent auth

  1. Publish the server (the toggle appears once the server is live).

  2. On the Publish page, switch on Agent Auth (auth.md).

  3. FlowCP shows the server's auth.md URL to copy and immediately begins advertising the discovery artifacts below. Toggle it off at any time to stop.

What gets published

When agent auth is enabled for a server at https://<runtime>/mcp/<serverId>, FlowCP serves:

Artifact
URL

auth.md file

https://<runtime>/mcp/<serverId>/auth.md

Protected Resource Metadata (RFC 9728)

https://<runtime>/.well-known/oauth-protected-resource/mcp/<serverId>

Authorization Server Metadata (RFC 8414)

https://<api>/.well-known/oauth-authorization-server/mcp/<serverId>

The auth.md file is a short Markdown document that doubles as human documentation and a machine-readable runtime artifact. It lists the server's resource URL, OAuth endpoints, requested scopes, and enabled tools.

The machine source of truth is the agent_auth block carried in the Protected Resource Metadata (and mirrored into the Authorization Server Metadata). It advertises skill (the auth.md URL), the registration endpoints (register_uri, claim_uri, revocation_uri), and the supported identity, assertion, and credential types.

The discovery chain

An agent reaches a server's auth.md the same way any MCP client discovers auth:

  1. The agent calls /mcp/<serverId> and receives 401 with a WWW-Authenticate: Bearer resource_metadata="…" header.

  2. It fetches the Protected Resource Metadata, which names the authorization server and carries the agent_auth block.

  3. It follows agent_auth.skill to read /mcp/<serverId>/auth.md.

From there the agent authenticates with the standard OAuth 2.0 authorization-code flow (with PKCE) — exactly the user-context OAuth FlowCP enforces on every call. See Configure OAuth to set up the provider.

Registration flows

Beyond discovery, FlowCP implements both auth.md agent-registration flows. The agent_auth block advertises only the flows that are actually live for a server, so an agent is never pointed at a flow that would fail:

Identity type
Flow
Advertised when

anonymous

User claimed — device-style claim ceremony

The server uses user_oauth mode with an OAuth config assigned

identity_assertion

Agent verified — ID-JAG signed identity assertion

The workspace has at least one trusted issuer

User claimed (anonymous)

A device-authorization-style ceremony for agents that have no registration of their own:

  1. The agent POSTs to agent_auth.claim_uri (/oauth/agent/claim) with a PKCE code_challenge and the server's resource URL. It receives a device_code, a human-readable user_code (XXXX-XXXX), a verification_uri, and a polling interval.

  2. The agent shows the code to its user, who signs in to the FlowCP dashboard, opens the Claim page, enters the code, and reviews the consent card (which agent, which server). See Claim an agent.

  3. Approving routes the user through the app's standard OAuth sign-in — the same user-context OAuth as every other flow — so the agent only ever acts in that user's authorization context.

  4. The agent polls the token endpoint with grant_type=urn:ietf:params:oauth:grant-type:device_code (receiving authorization_pending / slow_down until the user finishes) and redeems the result with its PKCE code_verifier. The tokens it receives are exactly what the standard authorization-code flow would have produced.

Agent verified (identity_assertion)

Agents that hold a signed JWT identity assertion (an ID-JAG, urn:ietf:params:oauth:token-type:id-jag) from an identity provider you trust can register directly:

  1. The agent POSTs to agent_auth.register_uri (/oauth/agent/register) with identity_type=identity_assertion, the assertion, and the server's resource URL.

  2. FlowCP verifies the assertion strictly — signature against the issuer's JWKS, exact issuer and audience, expiry, single-use jti, and an optional per-issuer subject allowlist — and returns an RFC 7591-style client registration carrying the verified identity.

  3. Registration establishes identity, never access: the registered client still obtains credentials through the standard authorization-code flow or the user-claimed ceremony above.

Every verification failure returns one generic invalid_assertion error, so the endpoint cannot be used to probe configuration.

Trusted issuers

Configure trusted issuers per workspace under Settings → Workspace → Trusted agent issuers: a display name, the issuer URL (exact iss match), and its JWKS URL (both must be https). Optionally restrict which sub values may register. While the list is empty, identity_assertion is not advertised and agent-verified registration is refused.

PreviousAgent-driven onboarding
NextClaim an agent

Last updated