Edvak Docs
HomeFHIR APICCDA API
HomeFHIR APICCDA API
LinkedIn
  1. Authentication & Authorization
  • Getting Started
    • Introduction
    • Supported Standards, Frameworks & API Versions
    • Standardized API Details – Patient and Population Services
    • Environment Endpoints
    • Errors and Exceptions
  • Authentication & Authorization
    • Overview – Authorization & Security Standards
    • Authorization
      • Well-known configuration
      • Authorize
      • Request
      • Revoke
      • Introspect
  • Developer Onboarding
    • App Registration & Credentials
  • API Usage Guidelines
    • FHIR API Interaction Conventions
  • US Core & USCDI Mapping
    • Overview
  • APIs
    • Allergies and Intolerances
      • By Patient ID
      • By Resource ID
    • Assessment and Plan of Treatment
      • By Patient and Category
    • Care Team Members
      • Care Teams
        • By Patient and Status
        • By Patient and Role
      • Related Person
        • By ID
        • By Patient
      • Practitioner
        • By Name
        • By Resource ID
        • By Identifier
      • Practioner Role
        • By Specialty
        • By Practitioner ID
        • By Practitioner Identifier
        • By Practitioner Name
      • Location
        • By Name
        • By Address
        • By City
        • By State
        • By Postal Code
      • Organization
        • By Name
        • By Address
    • Clinical Notes
      • Document References
        • By ID
        • By Patient
        • By Patient and Category
        • By Patient, Category, and Date
        • By Patient and Type
        • By Patient and Status
        • By Patient, Type, and Period
      • Diagnostic Report
        • By Patient ID
        • By Patient and Category
        • By Patient and Code
        • By Patient, Category, and Date
        • By Patient and Status
    • Goals
      • Get Goals by Patient ID
      • Get Goal by ID
      • Get Goals by Patient and Lifecycle Status
      • Get Goals by Patient and Target Date
      • Get Goals by Patient and Description
      • Get Diagnostic Reports by Patient, Code, and Date
    • Clinical Tests
      • Observation
        • By Patient and Category
        • By Patient and Code
        • By Patient, Code, and Date
        • By Patient, Category, and Date
        • By Patient, Category, and Status
      • Lab Diagnostic Report
        • By Patient
        • By Patient and Code
        • By Patient, Code, and Date
        • By Patient and Category
        • By Patient, Category, and Date
        • By Patient and Status
    • Diagnostic Imaging
      • Imaging Observations
        • By Patient
        • By Patient and Category
        • By Patient, Category, and Date
        • By Patient, Category, and Status
        • By Patient and Code
        • By Patient, Code and Date
    • Encounter Information
      • Encounter
        • By ID
        • By Patient ID
        • By Patient and Date Range
        • By Identifier
        • By Patient and Class
        • By Patient and Type
        • By Patient and Location
        • By Patient and Status
        • By Patient and Discharge Disposition
      • Encounter Diagnosis
        • By Patient ID
        • By Patient ID and Clinical Status
        • By Patient ID and Category
        • By Patient ID and Code
        • By Patient ID and Asserted Date
        • By Patient ID, Category, and Encounter
        • By Patient ID and Onset Date
        • By Patient ID and Recorded Date
        • By Patient ID and Abatement Date
    • Group
      • By ID
      • By $export (Group-level Bulk Export)
    • Health Concerns
      • By Patient
      • By Patient and Clinical Status
      • By Patient and Category
      • By Patient and Category and Encounter
      • By Patient and Code
      • By Patient and Asserted Date
      • By Patient and Onset Date
      • By Patient and Recorded Date
      • By Patient and Abatement Date
    • Implantable Devices
      • By Patient
      • By ID
      • By Patient and Type
    • Immunizations
      • By ID
      • By Patient
      • By Patient and Date
      • By Patient and Status
    • Laboratory
      • Laboratory Result Observation
        • By ID
        • By Patient and Category
        • By Patient, Category, and Date
        • By Patient, Category, and Status
        • By Patient and Code
        • By Patient, Code, and Date
    • Medications
      • Medications
        • By ID
        • By Patient
      • Medication Request
        • Get MedicationRequests by Patient
        • Get MedicationRequest by ID
        • Get MedicationRequests by Patient and Intent
        • Get MedicationRequests by Patient, Intent, and Encounter
        • Get MedicationRequests by Patient, Intent, and AuthoredOn Date
    • Patient Demographics
      • Patient
        • Get Patient by ID
        • Get Patient by Identifier
        • Get Patient by Name
        • Get Patient by Birthdate and Name
        • Get Patient by Gender and Name
        • Get Patient by Birthdate and Family Name
      • Observation Sexual Orientation
        • Get Observations by Patient ID
        • Get Observation by ID
        • Get Observations by Patient and Code
        • Get Observations by Patient, Code, and Date
        • Get Observations by Patient, Code, and Date
    • Procedures
      • Procedure
        • Get Procedures by Patient
        • Get Procedure by ID
        • Get Procedures by Patient and Date
        • Get Procedures by Patient and Status
        • Get Procedures by Patient, Code, and Date
      • Service Request
        • Get ServiceRequests by Patient
        • Get ServiceRequest by ID
        • Get ServiceRequests by Patient and Category
        • Get ServiceRequests by Patient and Code
        • Get ServiceRequests by Patient, Category, and Authored Date
        • Get ServiceRequests by Patient, Code, and Authored Date
        • Get ServiceRequests by Patient and Status
    • Provenance
      • Provenance
        • Get Provenance by ID
        • Get resource and Provenance using _revinclude
    • Smoking Status
      • Smoking Status
        • Get Observation by ID
        • Get Observations by Patient
        • Get Smoking Status by Patient and Code
    • Vital Signs
      • Vital Signs
        • Get Observation by ID
        • Get Observations by Patient and Category
        • Get Observations by Patient and Code
        • Get Observations by Patient, Category, and Date
        • Get Observations by Patient, Category, and Status
        • Get Observations by Patient, Code, and Date
  • Legal & Compliance
    • API Terms of Use
  1. Authentication & Authorization

Overview – Authorization & Security Standards

Edvak EHR secures access to its FHIR API endpoints through an OAuth 2.0-compliant authorization server, implementing the SMART on FHIR authorization framework. Applications interacting with FHIR resources must supply a Bearer token in each API request’s Authorization header.
Registered developers receive OAuth client credentials which are used to obtain access tokens from Edvak EHR's authorization server.

Technical Standards Followed#

OAuth 2.0 (RFC 6749)
OpenID Connect
SMART App Launch Framework v2.0.0

Supported OAuth Authorization Models#

1
Two-Legged OAuth (Client Credentials Flow)
Designed for backend services that need access without user interaction. Apps use their client credentials to obtain access tokens.
2
Three-Legged OAuth (Authorization Code Flow)
Used when user login and consent is required. Apps request authorization from the user and exchange the authorization code for an access token.

Scopes & Permissions#

OAuth scopes control what an application can access. In SMART on FHIR, scopes follow the format:
context/resource.access
Where:
context: patient, user, or system
resource: A specific FHIR resource (e.g. Condition) or * for all
access: read, write, or * for both

Examples#

ScopeDescription
patient/Condition.readRead Condition data for the current patient
system/Observation.readRead all Observations across patients
user/.Read and write all user-authorized resources
openid fhirUserRequest user identity and profile
launchGet context during launch from within the EHR
launch/patientRequest patient selection during standalone launch
offline_accessEnables long-lived access via refresh token
online_accessRefresh tokens valid while the user is online

Scope Evaluation Logic#

When scopes are requested, the authorization server checks:
1.
If the scopes are present in the request
2.
If the client is approved to request those scopes
3.
If end-user consent (when required) was granted
Scopes that are not approved or explicitly denied will not be included in the token. Apps can inspect granted scopes using token introspection.

Wildcard Scope Expansion#

Edvak Health supports wildcard expansion for patient, user, and system contexts.

patient/*.read includes:#

patient/Patient.read
patient/Condition.read
patient/Observation.read
patient/MedicationRequest.read
patient/Procedure.read
...and others

user/*.read includes:#

user/AllergyIntolerance.read
user/CarePlan.read
user/DocumentReference.read
user/ServiceRequest.read
...and others

system/*.read includes:#

system/Medication.read
system/Patient.read
system/Organization.read
system/Encounter.read
...and others

SMART on FHIR Authorization Workflow#

Applications may be launched from within Edvak Health EHR or as standalone apps.
1
Initiating Authorization
Apps construct a request to Edvak's authorization endpoint with:
response_type: code
client_id: App client ID
redirect_uri: Must match a registered redirect URI
scope: Requested permissions (e.g. openid patient/*.read)
state: CSRF protection value
aud: Base URL of the Edvak FHIR API
code_challenge & code_challenge_method: For PKCE (public clients)
2
End-User Authorization
Edvak presents a login and consent screen. Based on the response:
If granted: an authorization code is sent to the app’s redirect URI
If denied: an error response is returned
3
Exchanging Authorization Code for Access Token
Apps exchange the code for an access token:

Token Response Includes:#

access_token: Required for accessing APIs
token_type: Always "Bearer"
expires_in: Token lifetime (in seconds)
scope: Granted scopes
refresh_token: If offline or online access was requested
id_token: If OpenID Connect identity was requested

Refreshing an Access Token#

Access tokens issued by Edvak EHR are short-lived and designed to expire after a defined period, typically within 90 days, although this duration can vary based on organizational security policies.
To maintain continuous access without requiring a new user login, your application can use a refresh token to request a new access token from Edvak’s authorization server. Refresh tokens are designed for one-time use only — once used, they are immediately invalidated.
Each time a refresh token is successfully exchanged, the system issues a new refresh token, replacing the previous one. This rotation mechanism is a key security feature that reduces the risk of token theft or misuse. Generally, a refresh token remains valid for about 30 days, but any attempt to reuse a previous token will result in the associated access token being revoked.
Warning: Avoid Reusing Refresh Tokens
If a refresh token is reused — either intentionally or due to parallel requests — the system will:
Immediately invalidate that refresh token
Revoke all active access tokens issued through it
Block further token refresh attempts using that token
For this reason, it's critical to handle refresh tokens in a single-threaded or locked manner to prevent simultaneous use. Always securely store and replace tokens after each use.
POST /token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
refresh_token=YOUR_REFRESH_TOKEN
client_id=CLIENT_ID        (required for public apps)
client_secret=CLIENT_SECRET  (required for confidential apps)

Token Security Requirements#

Access tokens expire after ~1 hour
Refresh tokens may be valid up to 90 days
Always use HTTPS when exchanging or storing tokens
Tokens must be stored in secure app-specific storage
Responses include:
Cache-Control: no-store
Pragma: no-cache

JWKS (Optional Asymmetric Authentication)#

Edvak EHR supports public/private key pair authentication using JWKS (JSON Web Key Sets) for confidential clients.
To register your JWKS URI or public key, contact:
[email protected]

Accessing FHIR Resources#

API calls require a valid access token:
GET https://fhir-dev.edvak.com/fhir/Patient/123
Authorization: Bearer <ACCESS_TOKEN>

Additional Resources#

OAuth 2.0
SMART on FHIR
OpenID Connect
FHIR Specification
Modified at 2025-05-14 15:24:05
Previous
Errors and Exceptions
Next
Authorization
Built with