Discovery documents

Look up each document a project publishes about itself, with its URL, its standard, an example and what every field means.

A discovery document tells a client where a project's endpoints are and what they accept. Every document is on your project's issuer, the project's URL, and needs no authentication. The examples use https://acme.authfi.io.

Document	Describes	Standard
`/.well-known/openid-configuration`	Sign-in for people and applications	OpenID Connect Discovery
`/.well-known/oauth-authorization-server`	The token endpoint for AI agents	RFC 8414
`/.well-known/agent-configuration`	Agent endpoints and approval methods	AuthFI
`/.well-known/oauth-protected-resource`	The MCP gateway as a protected resource	RFC 9728
`/.well-known/jwks.json`	The project's public signing keys	RFC 7517
`/.well-known/ssf-configuration`	Revocation events you can subscribe to	OpenID Shared Signals

Read endpoints from these documents instead of hard-coding them. See Projects.

OpenID configuration

Describes sign-in for people and applications. An OpenID Connect library configures itself from this document.

GET

/.well-known/openid-configuration

Example request.

curl https://acme.authfi.io/.well-known/openid-configuration

Example response.

{
  "issuer": "https://acme.authfi.io",
  "authorization_endpoint": "https://acme.authfi.io/oauth/authorize",
  "token_endpoint": "https://acme.authfi.io/oauth/token",
  "userinfo_endpoint": "https://acme.authfi.io/oauth/userinfo",
  "jwks_uri": "https://acme.authfi.io/.well-known/jwks.json",
  "revocation_endpoint": "https://acme.authfi.io/oauth/token/revoke",
  "end_session_endpoint": "https://acme.authfi.io/oauth/logout",
  "introspection_endpoint": "https://acme.authfi.io/oauth/token/introspect",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token", "client_credentials"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["openid", "profile", "email", "offline_access"],
  "claims_supported": [
    "sub",
    "iss",
    "aud",
    "exp",
    "iat",
    "auth_time",
    "nonce",
    "at_hash",
    "c_hash",
    "email",
    "email_verified",
    "name",
    "scope",
    "groups",
    "roles"
  ],
  "acr_values_supported": [
    "urn:authfi:acr:1fa",
    "urn:authfi:acr:mfa",
    "urn:authfi:acr:passkey",
    "urn:authfi:acr:passkey_mfa"
  ]
}

Fields.

Field	Description
`issuer`	The project's issuer. It is the `iss` of every token.
`authorization_endpoint`	Authorize
`token_endpoint`	Token
`userinfo_endpoint`	Userinfo
`jwks_uri`	Keys
`revocation_endpoint`	Revoke a token
`end_session_endpoint`	Sign out
`introspection_endpoint`	Check a token
`response_types_supported`	`code`, the authorization code flow
`grant_types_supported`	The grants the token endpoint accepts
`subject_types_supported`	`public`
`id_token_signing_alg_values_supported`	`RS256`, the algorithm that signs ID tokens
`token_endpoint_auth_methods_supported`	HTTP Basic, the secret in the body, or no secret for an application without one
`code_challenge_methods_supported`	`S256`, the PKCE (RFC 7636) challenge method
`scopes_supported`	The scopes an application can request
`claims_supported`	The claims the project issues
`acr_values_supported`	The sign-in strengths an application can require

Used by Add sign-in to an app.

Authorization server metadata for agents

Describes the token endpoint that AI agents use. It is OAuth authorization server metadata (RFC 8414).

GET

/.well-known/oauth-authorization-server

Example request.

curl https://acme.authfi.io/.well-known/oauth-authorization-server

Example response.

{
  "issuer": "https://acme.authfi.io",
  "token_endpoint": "https://acme.authfi.io/apis/regional/v1/ai/auth/token",
  "jwks_uri": "https://acme.authfi.io/.well-known/jwks.json",
  "grant_types_supported": ["client_credentials", "urn:openid:params:grant-type:ciba"],
  "token_endpoint_auth_methods_supported": ["private_key_jwt"],
  "token_endpoint_auth_signing_alg_values_supported": ["EdDSA"],
  "access_token_signing_alg_values_supported": ["EdDSA"],
  "backchannel_authentication_endpoint": "https://acme.authfi.io/apis/regional/v1/ai/auth/backchannel-authorize",
  "backchannel_token_delivery_modes_supported": ["poll"],
  "backchannel_user_code_parameter_supported": false,
  "agent_configuration_endpoint": "https://acme.authfi.io/.well-known/agent-configuration",
  "response_types_supported": []
}

Fields.

Field	Description
`issuer`	The project's issuer
`token_endpoint`	Where an agent signs in and polls for an approval
`jwks_uri`	Keys
`grant_types_supported`	`client_credentials` for sign-in, and the CIBA grant
`token_endpoint_auth_methods_supported`	`private_key_jwt` (RFC 7523): a client assertion signed with the agent's key
`token_endpoint_auth_signing_alg_values_supported`	`EdDSA`, the algorithm an agent signs its assertion with
`access_token_signing_alg_values_supported`	`EdDSA`, the algorithm that signs agent access tokens
`backchannel_authentication_endpoint`	Where an agent asks a named person to approve
`backchannel_token_delivery_modes_supported`	`poll`: the agent polls the token endpoint for the answer
`backchannel_user_code_parameter_supported`	`false`
`agent_configuration_endpoint`	Agent configuration
`response_types_supported`	Empty. An agent signs in with its key, without a browser.

Explained in How agent sign-in works.

Agent configuration

Describes what an agent client needs beyond the OAuth metadata, such as the approval methods.

GET

/.well-known/agent-configuration

Example request.

curl https://acme.authfi.io/.well-known/agent-configuration

Fields.

Field	Value	Description
`modes`	`delegated`, `autonomous`	The two types of agent
`algorithms`	`EdDSA`	The signing algorithm
`agent_id_scheme`	`spiffe`	The scheme of an agent's identifier
`approval_methods`	`ciba`, `authfi_hitl`	How a person approves an action
`default_location`	`https://acme.authfi.io/mcp`	The project's MCP gateway
`endpoints.token`	`https://acme.authfi.io/apis/regional/v1/ai/auth/token`	The agent token endpoint
`endpoints.backchannel_authorize`	`https://acme.authfi.io/apis/regional/v1/ai/auth/backchannel-authorize`	The CIBA endpoint

Protected resource metadata

Describes the MCP gateway as a protected resource (RFC 9728), and names where to get a token for it.

GET

/.well-known/oauth-protected-resource

Example request.

curl https://acme.authfi.io/.well-known/oauth-protected-resource

Example response.

{
  "resource": "https://acme.authfi.io/mcp",
  "authorization_servers": ["https://acme.authfi.io"]
}

Fields.

Field	Description
`resource`	The MCP gateway's URL. Use it as `resource` at sign-in.
`authorization_servers`	The project's issuer, which issues tokens for the gateway

The gateway points to this document from the WWW-Authenticate header of a 401:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://acme.authfi.io/.well-known/oauth-protected-resource"

Used by Connect agents to tools and The MCP gateway.

Keys

Publishes the project's public signing keys as a JWK Set (RFC 7517).

GET

/.well-known/jwks.json

Example request.

curl https://acme.authfi.io/.well-known/jwks.json

Contents. One RS256 key and one EdDSA (Ed25519) key.

Key	Signs
`RS256`	ID tokens and access tokens for people and services
`EdDSA`	Tokens for AI agents

Match a token's kid header to a key in the set. After a rotation the previous key stays published for 24 hours. See Keys and secrets and Checking a token.

For cloud roles, AWS reads the project's keys from https://acme.authfi.io/oidc/.well-known/jwks.json.

Shared Signals configuration

Describes where to register a receiver for revocation events, and which events exist. It follows OpenID Shared Signals.

GET

/.well-known/ssf-configuration

Example request.

curl https://acme.authfi.io/.well-known/ssf-configuration

Example response.

{
  "issuer": "https://acme.authfi.io",
  "jwks_uri": "https://acme.authfi.io/.well-known/jwks.json",
  "configuration_endpoint": "https://acme.authfi.io/v1/ssf/streams",
  "delivery_methods_supported": ["urn:ietf:rfc:8935"],
  "events_supported": [
    "https://schemas.openid.net/secevent/caep/event-type/session-revoked",
    "https://schemas.openid.net/secevent/caep/event-type/token-claims-change",
    "https://schemas.openid.net/secevent/risc/event-type/account-purged",
    "https://schemas.openid.net/secevent/risc/event-type/credential-compromise"
  ],
  "spec_version": "1_0"
}

Fields.

Field	Description
`issuer`	The project's issuer. It is the `iss` of every event.
`jwks_uri`	The keys that sign events
`configuration_endpoint`	Where an administrator registers a receiver
`delivery_methods_supported`	Delivery by HTTP `POST` (RFC 8935)
`events_supported`	The event types a receiver can request
`spec_version`	`1_0`

Used by Stop an agent.

SAML metadata

A project also publishes SAML 2.0 metadata, at these paths on the issuer.

Document	Describes	Used by
`/saml/metadata`	The project as an identity provider, with its certificate	Connect a SAML application
`/saml/sp/{name}/metadata`	The project as a service provider for one connection	Sign in with another identity provider

{name} is the name you give the connection.