Heads up — this page will change. Registering SMART client apps and managing their credentials will move to console.esus.health, which is currently in development. The SMART-on-FHIR OAuth 2.0 flow itself (authorize → token → Bearer on the FHIR API) is a standard and is not changing. We will update this page with the new client-registration flow when the console ships.

SMART on FHIR

ESUS implements SMART on FHIR OAuth 2.0 for secure, delegated authentication. SMART provides a standard way for third-party applications to obtain and use OAuth 2.0 tokens with FHIR-specific scopes.

For basic JWT and API Key authentication, see Getting Started → Authentication.

Authentication Flow

Client → /smart/authorize → Auth Code → /smart/token → Bearer Token → FHIR API

Discovery Endpoint

Before authenticating, fetch the SMART configuration:

curl https://api.esus.health/.well-known/smart-configuration

{
  "authorization_endpoint": "https://api.esus.health/smart/authorize",
  "token_endpoint": "https://api.esus.health/smart/token",
  "capabilities": [
    "launch-ehr",
    "client-public",
    "client-confidential-symmetric",
    "sso-openid-connect",
    "context-ehr-patient",
    "permission-patient",
    "permission-user"
  ],
  "scopes_supported": [
    "openid", "fhirUser",
    "patient/*.read", "patient/*.write",
    "user/*.read", "user/*.write",
    "system/*.read"
  ]
}

Step 1: Register Your Application

Register your app via the API (requires an admin JWT token):

curl -X POST https://api.esus.health/smart/apps \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My FHIR App",
    "redirectUris": ["https://myapp.com/callback"],
    "scopes": ["patient/*.read", "openid", "fhirUser"],
    "isConfidential": true
  }'

Response:

{
  "id": "app-12345",
  "clientId": "client-abc",
  "clientSecret": "secret-xyz",
  "redirectUris": ["https://myapp.com/callback"],
  "scopes": ["patient/*.read", "openid", "fhirUser"]
}

Step 2: Authorization Request (PKCE)

Redirect the user to the authorization endpoint with a PKCE code challenge:

GET https://api.esus.health/smart/authorize
  ?client_id=client-abc
  &response_type=code
  &scope=patient/*.read openid fhirUser
  &redirect_uri=https://myapp.com/callback
  &state=random-state-string
  &code_challenge=BASE64URL(SHA256(code_verifier))
  &code_challenge_method=S256

The user is prompted to log in and authorize the requested scopes. On success, they are redirected to your redirect_uri with an authorization code:

https://myapp.com/callback?code=AUTH_CODE&state=random-state-string

Step 3: Token Exchange

curl -X POST https://api.esus.health/smart/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://myapp.com/callback" \
  -d "client_id=client-abc" \
  -d "client_secret=secret-xyz" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "patient/*.read openid fhirUser",
  "patient": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "fhirUser": "Practitioner/a7b1c2d3-e4f5-6789-abcd-ef0123456789"
}

Step 4: Use the Token

curl https://api.esus.health/fhir/Patient/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Scopes

Refresh Tokens

curl -X POST https://api.esus.health/smart/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN" \
  -d "client_id=client-abc" \
  -d "client_secret=secret-xyz"

Managing Registered Apps

# List apps
GET https://api.esus.health/smart/apps

# Update an app
PUT https://api.esus.health/smart/apps/:id

# Delete an app
DELETE https://api.esus.health/smart/apps/:id