Design considerations - FHIR Works on AWS

Design considerations

Regional deployments

This solution uses Amazon Cognito, which is not currently available in all AWS Regions. You must launch this solution in an AWS Region where Amazon Cognito is available. For the most current availability by Region, refer to the AWS Regional Services List.


Multi-tenancy allows a single FHIR Works on AWS stack to serve as multiple FHIR servers for different tenants. FHIR Works on AWS uses a pooled infrastructure model for multi-tenancy. This means that all tenants share the same infrastructure (Amazon DynamoDB tables, Amazon S3 buckets, Amazon OpenSearch Service cluster, etc.), but the data is logically partitioned to ensure that tenants are prevented from accessing another tenant’s resources.

Turn on multi-tenancy

To turn on multi-tenancy, set the EnableMultiTenancy parameter to true when deploying the solution. When turned on, /tenant/<tenantId>/ is appended to the FHIR server URL. For example, a client with <tennantId> as tenantA would use the following URL to search for patients:

GET /tenant/<tenantID>/Patient

Turning on this setting provides each tenant a unique FHIR server-based URL.


Updating an existing (single-tenant) stack to enable multi-tenancy is a breaking change. Multi-tenant deployments use a different data partitioning strategy that renders the old, single-tenant, data inaccessible. If you wish to switch from single-tenant to a multi-tenant model, it is recommended that you create a new multi-tenant stack and then migrate the data from the old stack. Switching from multi-tenant to a single-tenant model is also a breaking change.

Tenant identifiers

Tenants are identified by a tenant ID in the auth token. A tenant ID is a string that can contain alphanumeric characters, dashes, and underscores and have a maximum length of 64 characters.

The deployment creates a custom claim custom:tenantId to the Cognito user pool. When creating users, a tenant ID needs to be assigned to the user.