Discover the authorization and token endpoints by fetching [base]/.well-known/smart-configuration; extract authorization_endpoint and token_endpoint.
Generate a code_verifier (a cryptographically random string, 43-128 characters) and derive code_challenge = BASE64URL(SHA256(code_verifier)).
Redirect the user's browser to the authorization_endpoint with parameters: response_type=code, client_id, redirect_uri, scope (e.g., 'launch/patient openid fhirUser patient/*.read'), state (random nonce), code_challenge, code_challenge_method=S256.
Handle the redirect back to redirect_uri; extract the code parameter and verify the state matches to prevent CSRF.
Exchange the code for tokens: POST to token_endpoint with grant_type=authorization_code, code, redirect_uri, client_id, and code_verifier; receive access_token, id_token, and refresh_token.
Use the access_token as a Bearer token for FHIR API calls; store the refresh_token securely and use it to obtain new access tokens before expiry.
Known gotchas
PKCE is mandatory for public clients and recommended for confidential clients in SMART v2; omitting it will cause rejection on servers enforcing SMART App Launch v2.
The scope 'launch/patient' in standalone launch indicates the app needs a patient in context; the server will prompt the user to select a patient if not predetermined.
Tokens are short-lived (often 15-60 minutes); build refresh logic before making multi-step workflows rather than relying on a single long-lived token.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp