Security

FHIRfly is designed for healthcare data, so security is foundational. This page covers our authentication security model and best practices for keeping your integration secure.

Best Practices

1. Never expose API keys in client-side code — Use server-side requests only
2. Rotate keys regularly — Use the dashboard to rotate compromised keys
3. Use minimal scopes — Only request the scopes you need
4. Monitor usage — Check your dashboard for unusual activity
5. Prefer OAuth2 for production — Short-lived tokens reduce risk compared to long-lived API keys

OAuth2 Client Credentials

FHIRfly uses standard OAuth2 client credentials (RFC 6749), the industry-standard baseline for server-to-server authentication:

• Client credentials (ID + secret) are sent over the wire during token exchange, protected by TLS encryption
• Short-lived tokens (10 minutes) limit the exposure window if a token is compromised
• Secrets are hashed server-side using argon2 — they are never stored in plaintext
• Tokens are signed JWTs verified via JWKS, preventing forgery

Stronger Alternatives (Future Roadmap)

For higher-security environments, two stronger authentication methods exist:

1. private_key_jwt (RFC 7523) — The client signs a JWT assertion with its own private key instead of sending a shared secret. The server only stores the client's public key, so nothing sensitive crosses the wire beyond TLS. This is what SMART on FHIR recommends for backend services in healthcare.

2. mTLS (Mutual TLS, RFC 8705) — The client presents a TLS certificate during the handshake. The secret never leaves the client at all. Used in high-security healthcare environments.

Both methods are significantly stronger than shared secrets but add operational complexity (key management, certificate rotation). FHIRfly's current approach is standard OAuth2 and appropriate for most use cases.