safire 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9d11ee8ab8db74c9b225f12835caaf092616a0044372252617783b6187e3043
-  data.tar.gz: 8d73cdb90ed9d4ca7ec1e028bfe3e68464c7284f73e2d101a084be346e9b0085
+  metadata.gz: b9d2b84cc65eff523a4f1a8c86c5c2fe4f2089917062c115a12fb840e52369b4
+  data.tar.gz: 0f9cb348d913947546dff15f2d5d7a7904ca62dfdbce01dd8117598811ce5ec9
 SHA512:
-  metadata.gz: bf3cd169be16cb9598f2de3f572d0efeeb6c0ed98826b0690588c684e15c2a95afc6cf340d35a53c0f6d9eebc11c59dafdcdd02e71b0ddb8fbf629071644d90b
-  data.tar.gz: 6beaec7923441fb46d8fc4cc193ffff16354bb60fb62f141a3a36131e22f275df3d4ddfa31dd5548eebb6ad3a8872cd952c4cc4ab9dc31968b9eb644b0d097be
+  metadata.gz: 955b05bf392bebc9202d4b4c623e7223a398a969e72a2ed399bf0d25b57436cf3b2bbc086c3cdc2902f22742c36139089ec59d0389f4708185920746575134b3
+  data.tar.gz: 146ef00d7041a656c401e580e24cd309901b28a9b0584b37074f7067a2c76fe2f6548369feaa7692940af3aafc6fd3c36d045623e835b0bfdb33c0b468350d07

data/CHANGELOG.md

@@ -7,13 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-04-04
+
+### Added
+
+- SMART Backend Services Authorization flow (`client_credentials` grant) via
+  `Safire::Client#request_backend_token` and `Safire::Protocols::Smart#request_backend_token`:
+  - Authenticates exclusively via a signed JWT assertion (RS384 or ES384); no redirect,
+    PKCE, or user interaction required
+  - Scope defaults to `["system/*.rs"]` when none is configured or provided
+  - `private_key` and `kid` can be overridden per call
+- `token_response_valid?` now accepts a `flow:` keyword argument (`:app_launch` default):
+  when `flow: :backend_services`, also validates `expires_in` presence (required per
+  SMART Backend Services spec)
+- `token_response_valid?` accepts both `"Bearer"` (SMART App Launch spec) and `"bearer"`
+  (SMART Backend Services) as valid `token_type` values; the non-compliance warning
+  now references the expected value for the active flow
+- `SmartMetadata#supports_backend_services?` returns `true` when the server advertises the
+  `client_credentials` grant type and supports `private_key_jwt` authentication
+  (i.e. `grant_types_supported` includes `"client_credentials"` and
+  `supports_asymmetric_auth?` is `true`)
+
+### Changed
+
+- Corrected spec name throughout: "SMART on FHIR" → "SMART App Launch" per the
+  [SMART App Launch IG](https://hl7.org/fhir/smart-app-launch/); Backend Services is
+  presented as a feature within the spec, not a separate spec
+- `redirect_uri` and `authorization_endpoint` are now optional in `Safire::Protocols::Smart`;
+  both are validated only when `authorization_url` is called (app launch flow)
+- `redirect_uri` is now optional in `Safire::ClientConfig` to support backend services
+  clients that operate without a redirect URI; the field is still validated when provided
+
+### Fixed
+
+- YARD API docs nav links broken after in-page navigation: relative hrefs from the nav
+  iframe were resolved against the parent window URL (which changes on each navigation)
+  instead of the iframe base; `bin/docs` now patches the generated `full_list.js` to
+  resolve links to absolute URLs before messaging the parent
+
 ## [0.1.0] - 2026-03-25
 
 ### Added
 
 - `Safire::Client` facade with `protocol:` (`:smart`) and `client_type:`
   (`:public`, `:confidential_symmetric`, `:confidential_asymmetric`) keywords
-- SMART on FHIR App Launch 2.2.0 support via `Safire::Protocols::Smart`:
+- SMART App Launch 2.2.0 support via `Safire::Protocols::Smart`:
   - Server metadata discovery from `/.well-known/smart-configuration`
   - Authorization URL builder for GET and POST-based authorization
     (`authorize-post` capability)

data/Gemfile

@@ -20,6 +20,7 @@ group :development do
 end
 
 group :test do
+  gem 'dotenv', '~> 3.0'
   gem 'simplecov', require: false
   gem 'simplecov-cobertura', require: false
   gem 'webmock', '~> 3.18'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    safire (0.1.0)
+    safire (0.2.0)
       activesupport (~> 8.0.0)
       addressable (~> 2.8)
       faraday (~> 2.14)
@@ -47,6 +47,7 @@ GEM
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
     docile (1.4.1)
+    dotenv (3.2.0)
     drb (2.2.3)
     erb (5.0.3)
     faraday (2.14.1)
@@ -167,6 +168,7 @@ PLATFORMS
 DEPENDENCIES
   bundler-audit (~> 0.9)
   debug
+  dotenv (~> 3.0)
   pry
   pry-byebug
   rspec (~> 3.12)

data/README.md

@@ -5,19 +5,20 @@
 [![Coverage](https://codecov.io/gh/vanessuniq/safire/branch/main/graph/badge.svg)](https://codecov.io/gh/vanessuniq/safire)
 [![Documentation](https://img.shields.io/badge/docs-yard-blue.svg)](https://vanessuniq.github.io/safire)
 
-Safire is a lean Ruby library that implements [SMART on FHIR](https://hl7.org/fhir/smart-app-launch/) and [UDAP](https://hl7.org/fhir/us/udap-security/) client protocols for healthcare applications.
+Safire is a Ruby gem implementing the [SMART App Launch 2.2.0](https://hl7.org/fhir/smart-app-launch/) specification and the [UDAP Security](https://hl7.org/fhir/us/udap-security/) protocol for healthcare client applications. It handles OAuth 2.0 authorization against HL7 FHIR servers, covering PKCE, private key JWT assertions, and the Backend Services system-to-system flow, so you can focus on your application rather than protocol plumbing.
 
 ---
 
 ## Features
 
-### SMART on FHIR App Launch (v2.2.0)
+### SMART App Launch (v2.2.0)
 
 - Discovery (`/.well-known/smart-configuration`)
 - Public Client (PKCE)
 - Confidential Symmetric Client (`client_secret` + HTTP Basic Auth)
 - Confidential Asymmetric Client (`private_key_jwt` with RS384/ES384)
 - POST-Based Authorization
+- Backend Services (`client_credentials` grant, JWT assertion, no user interaction or PKCE; scope defaults to `system/*.rs`)
 
 ### UDAP
 
@@ -46,10 +47,12 @@ require 'safire'
 
 # Step 1 — Create a client (Hash config or Safire::ClientConfig.new)
 client = Safire::Client.new(
-  base_url:     'https://launch.smarthealthit.org/v/r4/sim/eyJoIjoiMSJ9/fhir',
-  client_id:    'my_client_id',
-  redirect_uri: 'https://myapp.example.com/callback',
-  scopes:       ['openid', 'profile', 'patient/*.read']
+  {
+    base_url:     'https://launch.smarthealthit.org/v/r4/sim/eyJoIjoiMSJ9/fhir',
+    client_id:    'my_client_id',
+    redirect_uri: 'https://myapp.example.com/callback',
+    scopes:       ['openid', 'profile', 'patient/*.read']
+  }
 )
 
 # Step 2 — Discover SMART metadata (lazy — only called when needed)
@@ -98,6 +101,35 @@ client = Safire::Client.new(
 # Authorization and token exchange are identical — Safire builds the JWT assertion automatically
 ```
 
+### Backend Services (system-to-system)
+
+No user interaction, redirect URI, or PKCE required — the client authenticates entirely via a signed JWT assertion:
+
+```ruby
+client = Safire::Client.new(
+  {
+    base_url:    'https://fhir.example.com',
+    client_id:   'my_backend_client',
+    private_key: OpenSSL::PKey::RSA.new(File.read('private_key.pem')),
+    kid:         'my-key-id-123',
+    scopes:      ['system/Patient.rs', 'system/Observation.rs']
+  }
+)
+
+token_data = client.request_backend_token
+# token_data => { "access_token" => "...", "token_type" => "Bearer", "expires_in" => 300, ... }
+
+# Override scope or credentials per call
+token_data = client.request_backend_token(
+  scopes:      ['system/Patient.rs'],
+  private_key: OpenSSL::PKey::RSA.new(File.read('new_key.pem')),
+  kid:         'new-key-id'
+)
+
+# Validate the token response (flow: :backend_services also checks expires_in)
+client.token_response_valid?(token_data, flow: :backend_services)
+```
+
 ---
 
 ## Configuration
@@ -122,7 +154,7 @@ bin/demo
 # Visit http://localhost:4567
 ```
 
-Demonstrates SMART discovery, all authorization flows, and token refresh. See [`examples/sinatra_app/README.md`](examples/sinatra_app/README.md) for details.
+Demonstrates SMART discovery, all authorization flows, token refresh, and backend services token requests. See [`examples/sinatra_app/README.md`](examples/sinatra_app/README.md) for details.
 
 ---
 

data/ROADMAP.md

@@ -1,6 +1,6 @@
 # Safire Roadmap
 
-## Current Release — v0.0.1
+## Current Release — v0.1.0
 
 Safire is in early development (pre-release). The API is functional but not yet stable — breaking changes may occur before v1.0.0. Published to [RubyGems](https://rubygems.org/gems/safire).
 
@@ -10,7 +10,7 @@ Feedback, bug reports, and pull requests are welcome via the [issue tracker](htt
 
 ## Implemented Features
 
-### SMART on FHIR App Launch (v2.2.0)
+### SMART App Launch (v2.2.0)
 
 - **Discovery** — lazy fetch of `/.well-known/smart-configuration`; metadata cached per client instance
 - **Public Client** — PKCE-only authorization code flow (RS256/ES256)
@@ -19,14 +19,14 @@ Feedback, bug reports, and pull requests are welcome via the [issue tracker](htt
 - **POST-Based Authorization** — form-encoded authorization requests
 - **JWT Assertion Builder** — signed JWT assertions with configurable `kid` and expiry
 - **PKCE** — automatic code verifier and challenge generation
+- **Backend Services** — `client_credentials` grant for system-to-system flows; JWT assertion (RS384/ES384); no user interaction, redirect, or PKCE required; scope defaults to `system/*.rs` when not configured
 
 ---
 
 ## Planned Features
 
-### SMART on FHIR
+### SMART App Launch
 
-- **Backend Services** — `client_credentials` grant for system-to-system flows (no user interaction)
 - **Dynamic Client Registration** — programmatic client registration per [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)
 
 ### UDAP Security

data/docs/Gemfile.lock

@@ -4,7 +4,7 @@ GEM
     addressable (2.8.8)
       public_suffix (>= 2.0.2, < 8.0)
     base64 (0.3.0)
-    bigdecimal (4.0.1)
+    bigdecimal (4.1.1)
     colorator (1.1.0)
     concurrent-ruby (1.3.6)
     csv (3.3.5)
@@ -140,7 +140,7 @@ DEPENDENCIES
 CHECKSUMS
   addressable (2.8.8) sha256=7c13b8f9536cf6364c03b9d417c19986019e28f7c00ac8132da4eb0fe393b057
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
-  bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
+  bigdecimal (4.1.1) sha256=1c09efab961da45203c8316b0cdaec0ff391dfadb952dd459584b63ebf8054ca
   colorator (1.1.0) sha256=e2f85daf57af47d740db2a32191d1bdfb0f6503a0dfbc8327d0c9154d5ddfc38
   concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
   csv (3.3.5) sha256=6e5134ac3383ef728b7f02725d9872934f523cb40b961479f69cf3afa6c8e73f

data/docs/_config.yml

@@ -19,7 +19,10 @@
 # in the templates via {{ site.myvariable }}.
 
 title: Safire Documentation
-description: SMART on FHIR and UDAP implementation library for Ruby
+tagline: Ruby gem for SMART App Launch and UDAP protocols
+description: SMART App Launch and UDAP implementation library for Ruby
+author: Vanessa Fotso
+lang: en-US
 baseurl: /safire
 url: https://vanessuniq.github.io
 

data/docs/adr/ADR-002-facade-and-forwardable.md

@@ -13,7 +13,7 @@ nav_order: 2
 
 ## Context
 
-Safire must support multiple authorization protocols (SMART on FHIR, UDAP) from a single public entry point. There are several ways to structure this:
+Safire must support multiple authorization protocols (SMART App Launch, UDAP) from a single public entry point. There are several ways to structure this:
 
 **Option A — Monolithic `Client`:** implement all protocol logic directly inside `Safire::Client`. Simple at first, but grows unbounded as each protocol adds methods, and makes it impossible to test protocol logic in isolation.
 

data/docs/adr/ADR-003-protocol-vs-client-type.md

@@ -13,7 +13,7 @@ nav_order: 3
 
 ## Context
 
-`Safire::Client` needs to support multiple healthcare authorization protocols (SMART on FHIR, UDAP) and, within SMART, multiple client authentication methods (public, confidential symmetric, confidential asymmetric). There are two ways to model this:
+`Safire::Client` needs to support multiple healthcare authorization protocols (SMART, UDAP) and, within SMART, multiple client authentication methods (public, confidential symmetric, confidential asymmetric). There are two ways to model this:
 
 **Option A — flat enum:** a single parameter enumerating every combination.
 

data/docs/adr/ADR-006-lazy-discovery.md

@@ -13,7 +13,7 @@ nav_order: 6
 
 ## Context
 
-SMART on FHIR clients need the authorization server's endpoints (`authorization_endpoint`, `token_endpoint`) to build authorization URLs and request tokens. These are obtained by fetching `/.well-known/smart-configuration`. There are two approaches:
+SMART clients need the authorization server's endpoints (`authorization_endpoint`, `token_endpoint`) to build authorization URLs and request tokens. These are obtained by fetching `/.well-known/smart-configuration`. There are two approaches:
 
 **Option A — eager discovery:** fetch metadata in `Smart#initialize`.
 

data/docs/adr/ADR-008-warn-return-false-for-compliance-validation.md

@@ -25,7 +25,7 @@ The question is: what should compliance checks do when they find a violation?
 
 **Option B — Warn and return false:** log a warning via `Safire.logger` for each violation found, then return `false`. Never raise.
 
-Option A treats a non-compliant server as an unrecoverable error. In practice, some production FHIR servers have minor token response non-compliance (e.g. `token_type: "bearer"` in lowercase rather than `"Bearer"`) but are otherwise functional. Raising an exception would prevent Safire from working with those servers entirely, with no way for callers to override the decision.
+Option A treats a non-compliant server as an unrecoverable error. In practice, some production FHIR servers have minor token response non-compliance (e.g. returning `token_type: "BEARER"` instead of the spec-required value) but are otherwise functional. Raising an exception would prevent Safire from working with those servers entirely, with no way for callers to override the decision.
 
 Option B lets the caller decide what to do: they can check the return value, observe the warnings in their logs, and choose to proceed or abort. This is consistent with how Ruby standard library methods (e.g. `URI.parse`, `JSON.parse` with `rescue nil`) handle validation — surface the issue, let the caller decide.
 
@@ -38,9 +38,9 @@ There is also a clear boundary: **the caller controls the config** (configuratio
 Compliance validation methods use the **warn + return false** pattern:
 
 ```ruby
-def token_response_valid?(response)
+def token_response_valid?(response, flow: :app_launch)
   # ...
-  Safire.logger.warn("SMART token response non-compliance: token_type is #{...}; expected 'Bearer'")
+  Safire.logger.warn("SMART token response non-compliance: token_type is #{...}; expected 'Bearer' (SMART App Launch spec)")
   false
 end
 
@@ -72,3 +72,4 @@ Configuration validation (`ClientConfig#validate!`, `Smart#validate!`) raises `C
 **Trade-offs:**
 - Callers who do not call `token_response_valid?` get no compliance signal at all — non-compliant responses are silently accepted; this is intentional (opt-in, not opt-out)
 - The distinction between "warn + return false" and "raise" must be maintained consistently — new validation methods should follow the same rule: server behaviour → warn; caller configuration → raise
+- `token_response_valid?` accepts a `flow:` keyword argument (`:app_launch` default, `:backend_services`) that adjusts which fields are required and what the warning messages say. For example, `token_type` must be `"Bearer"` (App Launch spec) or `"bearer"` (Backend Services spec), and `expires_in` is RECOMMENDED for App Launch but REQUIRED for Backend Services. Callers opt in to the stricter backend-services validation by passing `flow: :backend_services`

data/docs/configuration/client-setup.md

@@ -23,10 +23,12 @@ Pass configuration as a Hash — Safire wraps it in a `ClientConfig` automatical
 
 ```ruby
 client = Safire::Client.new(
-  base_url:     'https://fhir.example.com/r4',
-  client_id:    'my_client_id',
-  redirect_uri: 'https://myapp.com/callback',
-  scopes:       ['openid', 'profile', 'patient/*.read']
+  {
+    base_url:     'https://fhir.example.com/r4',
+    client_id:    'my_client_id',
+    redirect_uri: 'https://myapp.com/callback',
+    scopes:       ['openid', 'profile', 'patient/*.read']
+  }
 )
 ```
 
@@ -105,7 +107,7 @@ metadata = client.server_metadata
 client.client_type = :confidential_asymmetric if metadata.supports_asymmetric_auth?
 ```
 
-For a decision guide on which client type to use, see [SMART on FHIR — Choosing a Client Type]({{ site.baseurl }}/smart-on-fhir/).
+For a decision guide on which workflow to use, see [SMART App Launch — Choosing a Workflow]({{ site.baseurl }}/smart-on-fhir/).
 
 ---
 
@@ -122,7 +124,7 @@ The following attributes are validated:
 | Attribute | Validated when |
 |-----------|----------------|
 | `base_url` | Always |
-| `redirect_uri` | Always |
+| `redirect_uri` | When provided (required for App Launch; not used in Backend Services) |
 | `issuer` | When provided (defaults to `base_url`) |
 | `authorization_endpoint` | When provided |
 | `token_endpoint` | When provided |
@@ -155,4 +157,4 @@ config.inspect
 ## Next Steps
 
 - [Logging]({{ site.baseurl }}/configuration/logging/) — configure Safire's logger and HTTP request logging
-- [SMART on FHIR Workflows]({{ site.baseurl }}/smart-on-fhir/) — step-by-step authorization flow guides
+- [SMART App Launch Workflows]({{ site.baseurl }}/smart-on-fhir/) — step-by-step authorization flow guides

data/docs/index.md

@@ -3,6 +3,7 @@ layout: default
 title: Home
 nav_order: 1
 permalink: /
+description: "Safire is a Ruby gem implementing SMART App Launch 2.2.0 and UDAP Security protocols for healthcare client applications, with full support for OAuth 2.0 authorization against HL7 FHIR servers."
 ---
 
 # Safire Documentation
@@ -10,7 +11,7 @@ permalink: /
 [![Gem Version](https://badge.fury.io/rb/safire.svg)](https://badge.fury.io/rb/safire)
 [![CI](https://github.com/vanessuniq/safire/workflows/CI/badge.svg)](https://github.com/vanessuniq/safire/actions)
 
-A lean Ruby gem implementing **[SMART on FHIR](https://hl7.org/fhir/smart-app-launch/)** and **[UDAP](https://hl7.org/fhir/us/udap-security/)** protocols for clients.
+A lean Ruby gem implementing **[SMART App Launch](https://hl7.org/fhir/smart-app-launch/)** and **[UDAP](https://hl7.org/fhir/us/udap-security/)** protocols for clients.
 
 ## Quick Navigation
 
@@ -18,7 +19,7 @@ A lean Ruby gem implementing **[SMART on FHIR](https://hl7.org/fhir/smart-app-la
 |---------|-------------|
 | [Getting Started]({{ site.baseurl }}/installation/) | Install Safire and quick start guide |
 | [Configuration]({{ site.baseurl }}/configuration/) | All configuration options and parameters |
-| [SMART on FHIR]({{ site.baseurl }}/smart-on-fhir/) | Discovery, Public clients, Confidential clients |
+| [SMART]({{ site.baseurl }}/smart-on-fhir/) | App Launch (Public, Confidential Symmetric, Confidential Asymmetric) and Backend Services |
 | [UDAP]({{ site.baseurl }}/udap/) | UDAP protocol overview and planned support |
 | [Security Guide]({{ site.baseurl }}/security/) | HTTPS, credential protection, token storage, key rotation |
 | [Advanced Examples]({{ site.baseurl }}/advanced/) | Caching, multi-server, token management, complete Rails integration |
@@ -27,13 +28,14 @@ A lean Ruby gem implementing **[SMART on FHIR](https://hl7.org/fhir/smart-app-la
 
 ## Features
 
-### SMART on FHIR App Launch
+### SMART App Launch
 
 - Discovery (`/.well-known/smart-configuration`)
 - Public Client (PKCE)
 - Confidential Symmetric Client (client_secret + Basic Auth)
 - Confidential Asymmetric Client (private_key_jwt with RS384/ES384)
 - POST-Based Authorization
+- Backend Services (client_credentials grant, JWT assertion, no user interaction or PKCE)
 
 ### UDAP
 
@@ -47,7 +49,7 @@ A Sinatra-based demo app is included to help you explore Safire's features:
 bin/demo
 ```
 
-Visit http://localhost:4567 to test SMART discovery, authorization flows, and token management.
+Visit http://localhost:4567 to test SMART discovery, authorization flows, token management, and backend services token requests.
 
 See [`examples/sinatra_app/README.md`](https://github.com/vanessuniq/safire/tree/main/examples/sinatra_app) for details.
 

data/docs/installation.md

@@ -2,6 +2,7 @@
 layout: default
 title: Installation
 nav_order: 2
+description: "How to install the Safire Ruby gem and get started with SMART App Launch and UDAP authorization in your healthcare application."
 ---
 
 # Installation
@@ -71,10 +72,12 @@ A quick smoke test to confirm the gem is installed and SMART discovery is workin
 require 'safire'
 
 client = Safire::Client.new(
-  base_url:     'https://launch.smarthealthit.org/v/r4/sim/eyJoIjoiMSJ9/fhir',
-  client_id:    'test',
-  redirect_uri: 'https://example.com/callback',
-  scopes:       ['openid', 'profile', 'patient/*.read']
+  {
+    base_url:     'https://launch.smarthealthit.org/v/r4/sim/eyJoIjoiMSJ9/fhir',
+    client_id:    'test',
+    redirect_uri: 'https://example.com/callback',
+    scopes:       ['openid', 'profile', 'patient/*.read']
+  }
 )
 
 metadata = client.server_metadata
@@ -91,6 +94,6 @@ If you see an authorization endpoint URL, the gem is working. For troubleshootin
 | | |
 |-|-|
 | [Configuration]({{ site.baseurl }}/configuration/) | Client credentials, logging, and protocol selection |
-| [SMART on FHIR]({{ site.baseurl }}/smart-on-fhir/) | Authorization flows for public and confidential clients |
+| [SMART App Launch]({{ site.baseurl }}/smart-on-fhir/) | Authorization flows for public, confidential clients, and Backend Services |
 | [Security Guide]({{ site.baseurl }}/security/) | HTTPS requirements, credential protection, token storage |
 | [API Reference]({{ site.baseurl }}/api/){:target="_blank"} | Complete YARD documentation |

data/docs/smart-on-fhir/backend-services/index.md

@@ -0,0 +1,92 @@
+---
+layout: default
+title: Backend Services Workflow
+parent: SMART
+nav_order: 6
+has_children: true
+permalink: /smart-on-fhir/backend-services/
+---
+
+# Backend Services Workflow
+
+{: .no_toc }
+
+<div class="code-example" markdown="1">
+System-to-system access token requests using the OAuth 2.0 `client_credentials` grant and mandatory JWT assertion authentication — no user interaction, redirect URI, or PKCE required.
+</div>
+
+---
+
+## Overview
+
+SMART Backend Services enables autonomous server-to-server FHIR access without involving a user. It is defined in the [SMART App Launch Backend Services](https://hl7.org/fhir/smart-app-launch/backend-services.html) specification.
+
+Instead of a redirect flow, the client:
+
+1. Registers with the authorization server following the [confidential asymmetric registration steps](https://hl7.org/fhir/smart-app-launch/client-confidential-asymmetric.html#registering-a-client-communicating-public-keys) (required by the spec)
+2. Builds a signed JWT assertion using its registered private key
+3. Posts the assertion to the token endpoint with `grant_type=client_credentials`
+4. Receives an access token directly — no authorization code, no callback, no PKCE
+
+Suitable for:
+
+- Scheduled data pipelines and batch jobs
+- System integrations that run without a logged-in user
+- Clinical quality reporting and analytics platforms
+- Any server-to-server FHIR workflow
+
+---
+
+## Key Differences from App Launch
+
+| Aspect | App Launch | Backend Services |
+|--------|------------|-----------------|
+| **Grant type** | `authorization_code` | `client_credentials` |
+| **User interaction** | Required | None |
+| **Redirect URI** | Required | Not used |
+| **PKCE** | Required | Not used |
+| **Client auth** | Varies by `client_type:` | JWT assertion always |
+| **Scopes** | `patient/`, `user/`, `openid` | `system/` |
+| **Refresh token** | Usually issued | Not issued |
+| **`expires_in`** | Recommended | Required |
+
+---
+
+## Prerequisites: Registration, Keys, and JWKS
+
+### Client Registration
+
+Before making any token requests, the client **SHALL** register with the authorization server following the [confidential asymmetric client registration](https://hl7.org/fhir/smart-app-launch/client-confidential-asymmetric.html#registering-a-client-communicating-public-keys) steps defined in the SMART App Launch specification. Registration communicates the client's public key(s) to the server, either via a JWKS URI or by uploading the JWKS directly.
+
+### Key Pair and JWKS
+
+Backend services use the same RSA or EC key pair infrastructure as the confidential asymmetric app launch flow — key generation, JWKS publishing, and algorithm selection are identical. See the [Confidential Asymmetric Client — Prerequisites]({% link smart-on-fhir/confidential-asymmetric/index.md %}#prerequisites-keys-jwks-and-algorithm) guide for full details.
+
+---
+
+## Client Setup
+
+`redirect_uri` and `scopes` are optional for backend services clients. If `scopes` is omitted, Safire defaults to `["system/*.rs"]` when `request_backend_token` is called.
+
+```ruby
+config = Safire::ClientConfig.new(
+  base_url:    ENV['FHIR_BASE_URL'],
+  client_id:   ENV['SMART_CLIENT_ID'],
+  private_key: OpenSSL::PKey::RSA.new(ENV['SMART_PRIVATE_KEY_PEM']),
+  kid:         ENV['SMART_KEY_ID'],
+  scopes:      ['system/Patient.rs', 'system/Observation.rs']  # optional
+)
+
+client = Safire::Client.new(config)
+```
+
+{: .note }
+> `client_type:` is not used for backend services — `request_backend_token` always authenticates via JWT assertion regardless of `client_type`.
+
+---
+
+## What's Next
+
+- [Token Request]({% link smart-on-fhir/backend-services/token-request.md %}) — Requesting a token, scope/credential overrides, flow diagram, validation, error handling, and proactive renewal
+- [Security Guide]({{ site.baseurl }}/security/) — Private key management and rotation
+- [Confidential Asymmetric Client]({% link smart-on-fhir/confidential-asymmetric/index.md %}) — The app launch counterpart that shares the same key infrastructure