Stop writing authorization code for your FHIR-based app

Stop writing authorization logic. Start using standards that do the work for you. Your future self (and your security team) will thank you.

The problem keeping healthcare devs up at night: You've got one API endpoint. Multiple user types. Different data access levels. And a tangled mess of authorization logic that breaks every time requirements change. Sound familiar?

The Traditional nightmare
You're building a healthcare app. Dr. Sarah needs to see ALL patient observations. Mike the lab tech should only see finalized lab results. Nothing else. So you write:

• Custom middleware
• Complex query filters
• Separate API endpoints
• 100+ unit tests
• Another 40 hours when requirements change

There's a better way. And it requires ZERO custom authorization code.
The Game-Changer: SMART Scopes + Keycloak Roles

Here's what blows mind: SMART on FHIR V2 lets you write scopes with query parameters: user/Observation.rs?category=laboratory&status=final
This means: "Read observations, but ONLY finalized lab results."

Combine this with Keycloak's composite roles and Aidbox, and something magical happens:The same API endpoint returns different data based on who's asking. Automatically.

How it actually works

Create basic roles (SMART scopes):

user/Observation.rs — All observations
user/Observation.rs?category=laboratory&status=final — Just lab results

Bundle into job functions:

• Physician role → Full observation access
• Lab Technician role → Restricted to finalized labs

Let Keycloak resolve roles into tokens.Let Aidbox FHIR server enforce the rules.

That's it. No custom code.

Dr. Sarah calls: GET /fhir/Observation

• Hemoglobin (lab result)
• Blood Pressure (vital sign)

Mike calls: GET /fhir/Observation

✅ Hemoglobin (lab result)
❌ Blood Pressure (filtered out)

Same endpoint. Same code. Different results. Zero custom filtering.

Why this changes everything

• No authorization code to maintain
• Change permissions in one place (Keycloak)
• Standards-based (SMART on FHIR V2)
• Fine-grained control without complexity
• Add new roles in minutes without touching code

Try it now
The complete working example is on GitHub with Docker Compose. Clone it, run docker compose up, and test both user types in 5 minutes.

Read the full article by our Software Engineer Aleksandr Kislitsyn at health-samurai.io