Skip to main content

Access Policies

Route: /AccessPolicy (FHIR Browser) Related pages: Edit Membership (/admin/members/:id), Create Client (/admin/clients/new), Create Bot (/admin/bots/new), Invite User (/admin/invite)

What is an Access Policy?​

An AccessPolicy is a FHIR resource that controls what a user, client application, or bot is allowed to read, write, create, or delete within the project.

Every entity with project access — human users, OAuth clients, bots — can have an Access Policy assigned. Without one, a user defaults to the project-wide permissions (usually full access for admins). For non-admin users and machine clients, an Access Policy is essential for restricting them to only the data they need.

Why Access Policies Are Critical​

Data Isolation​

ChartChat stores health data for potentially thousands of patients. Without access policies:

  • A bot with a bug could overwrite records across all patients
  • A third-party OAuth client could read or delete data it was never meant to see
  • A new staff member with admin-level access could accidentally modify production configuration

HIPAA Compliance​

HIPAA's "minimum necessary" principle requires that each system component accesses only the data required for its function. Access Policies enforce this at the API level — the server rejects any request that falls outside the policy's scope, regardless of what the caller tries to do.

Preventing Runaway Bots​

Bots are TypeScript functions that execute server-side in response to FHIR events. A bot misconfigured without an access policy runs as a project admin and can read/write anything. Assigning a narrow Access Policy to a bot is the primary safeguard against accidental mass data mutation.

How to Create an Access Policy​

Step 1 — Navigate to the AccessPolicy resource list​

From the Admin Portal sidebar, use the FHIR Browser. In the URL bar, navigate to:

/AccessPolicy

This shows all existing Access Policy resources in the project. You can review existing policies to understand what patterns are already in use before creating a new one.

Step 2 — Create a new AccessPolicy resource​

Click New (top right) or navigate to /AccessPolicy/new.

You will land on the FHIR resource editor. Fill in:

FieldDescription
nameA human-readable name for the policy (e.g., Read-Only Patient Data)
resourceAn array of resource access rules — one per resource type

Each resource entry has:

FieldTypeDescription
resourceTypestringThe FHIR resource type this rule applies to (e.g., Patient, Observation)
readonlybooleanIf true, the entity can only read — not create, update, or delete
hiddenFieldsstring[]Field names that will be stripped from responses (e.g., ssn, telecom)
readonlyFieldsstring[]Fields the entity can read but cannot modify
criteriastringA FHIR search filter expression — restricts access to only matching resources (e.g., Patient?_tag=org-123)

Step 3 — Save the policy​

Click OK or Save in the resource editor. The policy is now available for assignment.

Step 4 — Assign the policy​

Access Policies can be assigned in three places:

  1. To a user — go to /admin/users, click the user, then Edit Membership → set the Access Policy field.
  2. To a client application — go to /admin/clients/new and set the Access Policy when creating the client, or edit the ClientApplication resource directly.
  3. To a bot — go to /admin/bots/new and set the Access Policy when creating the bot, or edit the Bot resource directly.
  4. When inviting a user — go to /admin/invite and select an Access Policy before sending the invite.

Common Policy Patterns​

Read-only patient data​

A policy that allows reading Patient and Observation resources but nothing else:

{
  "resourceType": "AccessPolicy",
  "name": "Read-Only Patient and Observations",
  "resource": [
    {
      "resourceType": "Patient",
      "readonly": true
    },
    {
      "resourceType": "Observation",
      "readonly": true
    }
  ]
}

Bot with write access to a single resource type​

A bot that only creates AuditEvent records and nothing else:

{
  "resourceType": "AccessPolicy",
  "name": "Audit Event Writer Bot",
  "resource": [
    {
      "resourceType": "AuditEvent"
    }
  ]
}

Scoped access by compartment (patient-compartment bot)​

A bot that can read/write only for a specific patient (using criteria):

{
  "resourceType": "AccessPolicy",
  "name": "Single Patient Bot",
  "resource": [
    {
      "resourceType": "Observation",
      "criteria": "Observation?subject=Patient/abc123"
    }
  ]
}

Hide sensitive fields from a third-party client​

{
  "resourceType": "AccessPolicy",
  "name": "Third-Party Read — No PII",
  "resource": [
    {
      "resourceType": "Patient",
      "readonly": true,
      "hiddenFields": ["telecom", "address", "name"]
    }
  ]
}

Viewing and Editing Policies​

All AccessPolicy resources are browsable and editable via the FHIR Browser (/AccessPolicy). Click any policy to open its resource view, then go to the Edit tab to modify it using the form editor or the JSON tab to edit the raw JSON.

warning

Changing an Access Policy affects every user, client, and bot it is currently assigned to — immediately and without warning. Be careful when editing shared policies in production.

Technical Reference​

FHIR Resource type: AccessPolicy Server enforcement: Every FHIR API request passes through the server's access control layer. The AccessPolicy resource is evaluated before any database query or write is performed. Inheritance: If a user has no Access Policy assigned, they inherit the project's default permissions. For project admins, this means full read/write access to all resources in the project.

The AccessPolicyInput component (admin/AccessPolicyInput.tsx) is a reusable ResourceInput wrapper used in invite, membership edit, create client, and create bot forms throughout the Admin Portal.