HTTP API & integration reference

SMART Flint’s HTTP API is the integration boundary. SDKs are optional clients; the server exposes an OpenAPI 3.1 contract at:

https://your-flint-origin.example/api/openapi.json

Replace the example origin with the actual deployment origin. For the default source-development stack, use http://127.0.0.1:3001/api/openapi.json. For the default Docker sandbox, use http://127.0.0.1:3010/api/openapi.json. The contract is generated with the running service version and configured base URL; prefer that document when implementing against a particular deployment.

Interactive launch endpoints

Method and path	Purpose
GET /launch/{installationId}	Receive a registered EHR launch with the exact approved iss and upstream launch handle
GET /api/launches/bootstrap/{ticket}	Resolve the short-lived EHR bootstrap ticket before establishing the application’s transaction
POST /api/launches	Create a launch transaction bound to the application callback, state, and S256 PKCE challenge
GET /launch/start/{ticket}	Start upstream authorization in the initiating browser
GET /oauth/callback/{connectionId}	Complete the bound EHR OAuth exchange and deliver a one-use activation code to the application
POST /api/activations/redeem	Redeem the activation code using the matching downstream PKCE verifier, application ID, and exact redirect URI

Upstream authorization and downstream application activation use separate transaction binding. Do not implement redemption using only an activation ID or put a permanent application secret in a browser. The application integration guide shows how the SDK handles the browser sequence.

Activation and credential endpoints

These routes require a bearer activation session credential scoped to the activation in the path.

Method and path	Purpose
GET /api/activations/{activationId}	Read normalized launch context, endpoints, and access capabilities
DELETE /api/activations/{activationId}	Close local application activation access
GET /api/activations/{activationId}/credentials	Obtain current upstream access credentials when token export is permitted
GET /api/activations/{activationId}/credentials/original	Retrieve the explicit original-token response envelope and renewal-ownership metadata
POST /api/activations/{activationId}/credentials/handoff	Transfer supported credential lifecycle ownership once
GET or HEAD /fhir/{activationId}/{resourcePath}	Use the activation-bound read/search gateway

The original upstream token can have expired; use the current-credential provider for active direct requests. Refresh tokens are withheld while SMART Flint owns renewal. A closed local activation does not automatically revoke an upstream credential already exported. See access modes.

Backend and CDS Hooks endpoints

POST /api/service-activations creates pre-authorized backend access from an installationId, using the backend application’s server-held bearer API key. It returns an activation descriptor and a separate activation session credential. The application key authenticates that acquisition operation; later activation operations use the session credential.

GET /cds-services discovers enabled services. POST /cds-services/{serviceId} accepts the configured signed caller JWT and synchronous hook request. Caller authentication is separate from any invocation-bound fhirAuthorization supplied with the hook. See backend services and CDS Hooks for full examples.

Configuration, identity, and operations

The /api/admin/ endpoints manage reusable registry records, installation worksheets, local/OIDC users, application credentials, CDS service bindings, audit views, and operational counters. Use named administrative sessions and the roles/assignments described in administration. The explicit bootstrap bearer credential is for first-owner setup and is retired once an enabled owner exists; it is not a permanent application integration credential.

GET /health reports process liveness. GET /ready verifies dependency and signing-envelope access. GET /api/admin/operations returns platform-administrator-only process-local counters. GET /.well-known/jwks.json and GET /.well-known/jwks/{registrationId} publish the relevant public signing keys, not private key material.

Errors and versioning

The documented Problem shape contains a fixed code, message, and optional requestId. Retain the request ID and sanitized code for troubleshooting. Do not serialize full token responses or authorization transactions into diagnostics. Responses may contain additional optional fields; consumers should ignore unknown optional fields.

Use matching server, contracts, and SDK artifacts. Current 0.x artifacts remain prereleases. The published qualified-1.x compatibility policy describes how future stable major releases will handle breaking API changes; it does not turn 0.1 into a 1.0 release or establish upstream vendor compatibility.

Source references: OpenAPI implementation, launch routes, activation and gateway routes, and public contracts.