# 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](/concepts/projects).

## OpenID configuration

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

<Endpoint method="GET" path="/.well-known/openid-configuration" />

**Example request.**

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

**Example response.**

```json
{
  "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](/reference/oauth#authorize)                                                  |
| `token_endpoint`                        | [Token](/reference/oauth#token)                                                          |
| `userinfo_endpoint`                     | [Userinfo](/reference/oauth#userinfo)                                                    |
| `jwks_uri`                              | [Keys](#keys)                                                                            |
| `revocation_endpoint`                   | [Revoke a token](/reference/oauth#revoke-a-token)                                        |
| `end_session_endpoint`                  | [Sign out](/reference/oauth#sign-out)                                                    |
| `introspection_endpoint`                | [Check a token](/reference/oauth#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](/reference/oauth#scopes) an application can request                         |
| `claims_supported`                      | The [claims](/reference/tokens) the project issues                                       |
| `acr_values_supported`                  | The [sign-in strengths](/reference/tokens#acr-and-amr-values) an application can require |

Used by [Add sign-in to an app](/quickstart/sign-in).

## Authorization server metadata for agents

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

<Endpoint method="GET" path="/.well-known/oauth-authorization-server" />

**Example request.**

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

**Example response.**

```json
{
  "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](/quickstart/agent) and polls for an approval       |
| `jwks_uri`                                         | [Keys](#keys)                                                                |
| `grant_types_supported`                            | `client_credentials` for sign-in, and the [CIBA](/agents/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](/agents/ciba) 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](#agent-configuration)                                  |
| `response_types_supported`                         | Empty. An agent signs in with its key, without a browser.                    |

Explained in [How agent sign-in works](/agents/how-it-works).

## Agent configuration

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

<Endpoint method="GET" path="/.well-known/agent-configuration" />

**Example request.**

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

**Fields.**

| Field                             | Value                                                                   | Description                                          |
| --------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------- |
| `modes`                           | `delegated`, `autonomous`                                               | The [two types of agent](/agents/how-it-works)       |
| `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](/agents/approvals) |
| `default_location`                | `https://acme.authfi.io/mcp`                                            | The project's [MCP gateway](/agents/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](/agents/ciba) endpoint                    |

## Protected resource metadata

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

<Endpoint method="GET" path="/.well-known/oauth-protected-resource" />

**Example request.**

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

**Example response.**

```json
{
  "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
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](/quickstart/mcp) and [The MCP gateway](/agents/mcp-gateway).

## Keys

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

<Endpoint method="GET" path="/.well-known/jwks.json" />

**Example request.**

```bash
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](/security/keys) and [Checking a token](/reference/tokens#checking-a-token).

For [cloud roles](/access/cloud), 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.

<Endpoint method="GET" path="/.well-known/ssf-configuration" />

**Example request.**

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

**Example response.**

```json
{
  "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](#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](/agents/revocation).

## 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](/applications/saml)                    |
| `/saml/sp/{name}/metadata` | The project as a service provider for one connection      | [Sign in with another identity provider](/connections/sign-in-with) |

`{name}` is the name you give the connection.