OAuth Operation Scopes

In addition to standard SMART on FHIR clinical scopes, Aidbox supports custom OAuth scopes that control access to specific Aidbox operations. These scopes follow the same token-based authorization model but are not part of the SMART on FHIR specification.

When SMART on FHIR access control is active, requests to protected endpoints without the corresponding scope are rejected with HTTP 403 Forbidden.

These scopes only unlock access to the endpoint itself — they do not check SMART resource-level scopes (e.g. patient/Patient.r). An AccessPolicy that permits the request must still be in place. Without a matching AccessPolicy the request will be rejected even if the scope is present.

Supported scopes

ScopeEndpointDescription
aidbox_graphql/$graphqlGrants access to the GraphQL endpoint.
aidbox_viewdefinition_run/fhir/ViewDefinition/$run, /fhir/ViewDefinition/{id}/$runGrants access to run ViewDefinition operations.

These scopes are included in the scope claim of the JWT token alongside standard SMART scopes:

scope: "openid fhirUser patient/Patient.r aidbox_graphql aidbox_viewdefinition_run"

GraphQL scope

The aidbox_graphql scope controls access to the /$graphql endpoint.

Examples

Request with scope

POST /$graphql
Authorization: Bearer <token>
Content-Type: application/json

{"query": "query { PatientList { name { given family } } }"}

Token scope: openid fhirUser patient/Patient.r aidbox_graphql

Request without scope

POST /$graphql
Authorization: Bearer <token>
Content-Type: application/json

{"query": "query { PatientList { name { given family } } }"}

Token scope: openid fhirUser patient/Patient.r

ViewDefinition scope

The aidbox_viewdefinition_run scope controls access to the /fhir/ViewDefinition/$run and /fhir/ViewDefinition/{id}/$run endpoints.

Examples

Run ViewDefinition

POST /fhir/ViewDefinition/$run
Authorization: Bearer <token>
Content-Type: text/yaml
Accept: application/json

resourceType: Parameters
parameter:
  - name: viewResource
    resource:
      select:
        - column:
            - name: id
              path: id
      status: draft
      resource: Patient
      resourceType: ViewDefinition
  - name: _format
    valueCode: json

Token scope: openid fhirUser patient/Patient.r aidbox_viewdefinition_run

Request without scope

POST /fhir/ViewDefinition/$run
Authorization: Bearer <token>
Content-Type: text/yaml
Accept: application/json

resourceType: Parameters
parameter:
  - name: viewResource
    resource:
      select:
        - column:
            - name: id
              path: id
      status: draft
      resource: Patient
      resourceType: ViewDefinition
  - name: _format
    valueCode: json

Token scope: openid fhirUser patient/Patient.r

Last updated: