.well-known/smart-configuration

The JSON discovery document advertising a FHIR server's OAuth endpoints and SMART capabilities.

Definition

An app issues a GET to {fhirBase}/.well-known/smart-configuration and receives a JSON object whose required fields include authorization_endpoint and token_endpoint, plus optional fields such as jwks_uri, scopes_supported, token_endpoint_auth_methods_supported and capabilities (e.g. launch-ehr, permission-v2, client-confidential-asymmetric). All endpoint URLs in the response must be absolute.

Origin

Defined in the HL7 SMART App Launch implementation guide, "Conformance" section (STU 2.x); it follows the IETF Well-Known URI registry convention (RFC 8615).

Example in context

GET https://ehr/fhir/.well-known/smart-configuration → { "authorization_endpoint": "https://ehr/auth/authorize", "token_endpoint": "https://ehr/auth/token", "capabilities": ["launch-ehr","permission-v2"] }

Related terms

• SMART App Launch — the flow that consumes this document.
• SMART Backend Services — reads token_endpoint and jwks_uri from it.