Organization-based hierarchical access control

Achieve logical multi-tenancy with Aidbox

Hierarchical organization-based access control in Aidbox allows for the restriction of access to data based on the organization to which it belongs. When this feature is enabled, the FHIR Organization resource in Aidbox gains new semantics and functionality.

This means that when users interact with the Organizational FHIR API, they are only able to access the resources that belong to their organization or tenant. The hierarchical organization-based access control ensures that data is logically isolated and accessible only within the appropriate organizational context.


FHIR resources must be separated per organizations. Organizations can be nested. Every organization has access to their own resources and to the nested organization resources.


Let's consider the next organization structure. There are two independent organizations Org A & Org D, each of them has nested, dependent organizations. Org B & Org C are nested to Org A, and Org E is nested to Org D.

To achieve such a behavior, you may consider an Aidbox feature called organization-based access control.

Let's create the organization structure in Aidbox:

status: 200 OK
content-type: text/yaml
accept: text/yaml

- id: org-a
  resourceType: Organization
- id: org-b
  resourceType: Organization
  partOf: {resourceType: Organization, id: org-a}
- id: org-c
  resourceType: Organization
  partOf: {resourceType: Organization, id: org-a}
- id: org-d
  resourceType: Organization
- id: org-e
  resourceType: Organization
  partOf: {resourceType: Organization, id: org-d}

When an Organization resource is created, a dedicated FHIR API is deployed for that organization. This API provides access to the associated FHIR resources. Nested organization FHIR resources are accessible through the parent Organization API.

The Organization-based FHIR API base url:


The Organization-based Aidbox API base url:


Let's play with a new APIs.

We will create a Patient resource in Org B:

status: 201 Created
PUT /Organization/org-b/fhir/Patient/pt-1
content-type: text/yaml
accept: text/yaml

name: [{given: [John], family: Smith}]
gender: male

Now we can read it:

status: 200 OK
GET /Organization/org-b/fhir/Patient/pt-1

The resource is also accessible through Org A API:

status: 200 OK
GET /Organization/org-a/fhir/Patient/pt-1

But this resource is not accessible through Org C, Org D and Org E API:

status: 403 Forbidden
GET /Organization/org-c/fhir/Patient/pt-1

FHIR API over Organization resources



POST <AIDBOX_BASE_URL>/Organization/<org-id>/fhir/<resource-type>


GET <AIDBOX_BASE_URL>/Organization/<org-id>/fhir/<resource-type>/<id>


PUT <AIDBOX_BASE_URL>/Organization/<org-id>/fhir/<resource-type>/<id>

PATCH <AIDBOX_BASE_URL>/Organization/<org-id>/fhir/<resource-type>/<id>


DELETE <AIDBOX_BASE_URL>/Organization/<org-id>/fhir/<resource-type>/<id>
GET <AIDBOX_BASE_URL>/Organization/<org-id>/fhir/<resource-type>

The search API does not support search parameters:

  • _has

  • _assoc

  • _with


Resource full history

GET <AIDBOX_BASE_URL>/Organization/<org-id>/fhir/<resource-type>/<id>/_history

Specific version history entry

GET <AIDBOX_BASE_URL>/Organization/<org-id>/fhir/<resource-type>/<id>/_history/<vid>


Supported transaction and batch bundle type.

POST /Organization/org-b/fhir/
Accept: text/yaml
Content-Type: text/yaml

resourceType: Bundle
# transaction | batch
type: transaction
- request:
    method: POST
    url: 'Patient'
    birthDate: '2021-01-01'
    id: 'pt-1'
        id: 'org-c'
        resourceType: 'Organization'
- request:
    method: POST
    url: 'Patient'
    birthDate: '2021-01-01'
    id: 'pt-2'


GET <AIDBOX_BASE_URL>/Organization/<org-id>/fhir/metadata

Shared resource mode

By default, nested API has no access to a resource that belongs to the upper organizations. Sometimes it is necessary to have resources that can be accessed by the nested APIs. To achieve it the resource should be marked as share.

Create a shared resource

To create a shared resource, use the extension.

status: 201 Created
PUT /Organization/org-a/fhir/Practitioner/prac-1
content-type: text/yaml

  - url:
    valueString: "shared"

Access shared resource from a nested API

status: 200 OK
GET /Organization/org-b/fhir/Practitioner/prac-1

Last updated