FHIR ANT Getting Started

This guide walks you through your first session with FHIR ANT — from installation to making authenticated API calls.

Install#

Download FHIR ANT from the Google Play Store. It also runs as a Linux desktop app or a standalone CLI server (see CLI Usage).

First Launch#

When you open the app for the first time, you'll see a three-page onboarding:

1. Welcome — what FHIR ANT is
2. How It Works — features overview
3. Sample Data — optionally load a set of realistic clinical data (MIMIC-IV subset) to explore with

You can always load or clear sample data later. Tap Get Started to reach the dashboard.

The Dashboard#

The dashboard has four sections:

• Server Control — start/stop the server, toggle Dev Mode, set the port
• Network Info — your device's IP address and a QR code other devices can scan to connect
• Resource Counts — how many FHIR resources are stored, by type
• Request Log — live feed of incoming HTTP requests

Starting the Server#

Tap Start on the Server Control card. The server binds to all network interfaces on the configured port (default 8080). The URL will look something like:

http://192.168.1.42:8080

Any device on the same Wi-Fi network can reach this URL.

Dev Mode vs Authenticated Mode#

By default, the server starts in Dev Mode — authentication is disabled and all requests are accepted. This is useful for quick testing.

To require authentication, toggle Dev Mode off before starting the server. When Dev Mode is off, all non-public endpoints require a valid JWT token.

Using Dev Mode#

With Dev Mode on, you can immediately start making requests:

# Server capabilities
curl http://192.168.1.42:8080/metadata

# Search for all patients
curl http://192.168.1.42:8080/Patient

# Create a patient
curl -X POST http://192.168.1.42:8080/Patient \
  -H "Content-Type: application/fhir+json" \
  -d '{"resourceType":"Patient","name":[{"family":"Smith","given":["John"]}]}'

No tokens or credentials needed — every request is treated as an admin.

Setting Up Authentication#

When you're ready to use auth, stop the server, toggle Dev Mode off, and start it again.

Step 1: Check Server Status#

The /auth/status endpoint is public and tells you whether any users exist:

curl http://192.168.1.42:8080/auth/status

{"firstUser": true}

"firstUser": true means no users have been created yet.

Step 2: Create the Admin Account#

When no users exist, anyone can register — this is the bootstrap mechanism. The first user is automatically promoted to admin regardless of what role you request:

curl -X POST http://192.168.1.42:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "mysecurepassword"}'

{
  "id": 1,
  "token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "Bearer",
  "username": "admin",
  "role": "admin",
  "scopes": ["system/*.*"]
}

Registration returns a JWT immediately — you're logged in.

TOKEN="eyJ..."

# Search patients
curl -H "Authorization: Bearer $TOKEN" \
  http://192.168.1.42:8080/Patient

# Create a resource
curl -X POST http://192.168.1.42:8080/Observation \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Observation",
    "status": "final",
    "code": {"text": "Heart rate"},
    "valueQuantity": {"value": 72, "unit": "bpm"}
  }'

# Create a clinician (default role)
curl -X POST http://192.168.1.42:8080/auth/register \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "drjones", "password": "anothersecurepassword"}'

# Create a read-only user
curl -X POST http://192.168.1.42:8080/auth/register \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "viewer", "password": "viewersecurepassword", "role": "readonly"}'

curl -X POST http://192.168.1.42:8080/auth/register \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "labtech",
    "password": "labsecurepassword",
    "role": "clinician",
    "scopes": ["user/Observation.cruds", "user/DiagnosticReport.cruds", "user/Patient.rs"]
  }'

curl -X POST http://192.168.1.42:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "drjones", "password": "anothersecurepassword"}'

{
  "token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "Bearer",
  "username": "drjones",
  "role": "clinician",
  "scopes": ["user/*.*"]
}

curl -X POST http://192.168.1.42:8080/auth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "refresh_token", "refresh_token": "eyJ..."}'

curl -X POST http://192.168.1.42:8080/auth/logout \
  -H "Authorization: Bearer $TOKEN"

curl -X POST http://192.168.1.42:8080/auth/revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJ..."}'

# Search by name
curl "$BASE/Patient?name=smith"

# Search by date range
curl "$BASE/Observation?date=gt2024-01-01&date=lt2024-12-31"

# Include referenced resources
curl "$BASE/Observation?patient=Patient/123&_include=Observation:patient"

# Chain through references
curl "$BASE/Observation?patient.name=smith"

curl -X POST "$BASE/\$backup" -H "Authorization: Bearer $TOKEN" > backup.json

curl -X POST "$BASE/\$restore" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d @backup.json

final request = FhirSearchRequest(
  base: Uri.parse('http://192.168.1.42:8080'),
  type: R4ResourceType.Patient,
  parameters: FhirSearchParams(params: [
    SearchString(FhirSearchParamDefinition.familyParam, ['Smith']),
  ]),
);
final response = await request.request();

curl -X POST "$BASE/admin/unlock/2" -H "Authorization: Bearer $ADMIN_TOKEN"