CareTeam

The CareTeam validator implements access control based on FHIR CareTeam membership. It grants access to patient data when the authenticated client is a member of a CareTeam that is responsible for that patient's care. This validator is designed for care coordination scenarios where access needs to cross organizational boundaries.

Server-exclusive

The CareTeam validator is available only in Fire Arrow Server. It is not available in Fire Arrow Core.

When to use

Use the CareTeam validator when:

• Access should follow care relationships, not organizational boundaries. A specialist at a different hospital needs to see a patient's data because they are part of the patient's care team.
• Multidisciplinary teams coordinate care for a patient. A care team might include a primary care physician, a specialist, a social worker, and a home nurse — each from different organizations.
• Patient-to-patient access is needed, such as peer support programs where a patient mentor needs limited access to another patient's data.
• Caregivers and family members (represented as RelatedPerson) need access to a patient's data based on their role in the care team.
• Fine-grained role-based access within a team is needed, where different team members see different data based on their role on the team (e.g., a care coordinator vs. a consulting physician).

Supported client roles

Client role	Access model
Patient	Own compartment + cross-patient access via CareTeam subject
Practitioner	All patients in CareTeams where the practitioner is a member (direct, via role, or via organization)
RelatedPerson	Patients in CareTeams where the related person is a direct member

Device clients are not supported and will receive an error.

Understanding CareTeam membership

A FHIR CareTeam resource represents a group of practitioners, organizations, and other participants who are involved in the care of a specific patient. The key fields are:

• CareTeam.subject — the patient whose care this team coordinates.
• CareTeam.participant.member — references to team members. Can be a Practitioner, PractitionerRole, Organization, Patient, RelatedPerson, or even another CareTeam.
• CareTeam.participant.role — the role each member plays on the team (e.g., primary care provider, care coordinator, consulting specialist).
• CareTeam.status — only active CareTeams are considered for access control.
• CareTeam.participant.period — optional time bounds for participation. Expired participants are excluded.

Example CareTeam resource

{
  "resourceType": "CareTeam",
  "id": "diabetes-team-patient-123",
  "status": "active",
  "subject": {
    "reference": "Patient/patient-123"
  },
  "participant": [
    {
      "role": [{
        "coding": [{
          "system": "http://snomed.info/sct",
          "code": "446050000",
          "display": "Primary care provider"
        }]
      }],
      "member": {
        "reference": "Practitioner/dr-smith"
      }
    },
    {
      "role": [{
        "coding": [{
          "system": "http://snomed.info/sct",
          "code": "768820003",
          "display": "Care coordinator"
        }]
      }],
      "member": {
        "reference": "Practitioner/nurse-jones"
      }
    },
    {
      "role": [{
        "coding": [{
          "system": "http://snomed.info/sct",
          "code": "309343006",
          "display": "Physician"
        }]
      }],
      "member": {
        "reference": "Organization/downtown-clinic"
      }
    },
    {
      "member": {
        "reference": "RelatedPerson/spouse-456"
      }
    }
  ]
}

In this example, Dr. Smith, Nurse Jones, all practitioners at Downtown Clinic, and the patient's spouse all have access to Patient/patient-123's data through this CareTeam.

How membership is resolved

The CareTeam validator resolves membership differently depending on the client role:

Practitioner membership (three paths)

A practitioner can be a CareTeam member through three paths:

1. Direct membership — the practitioner is listed explicitly as CareTeam.participant.member (e.g., Practitioner/dr-smith).
2. Via PractitionerRole — one of the practitioner's PractitionerRole resources is listed as a member (e.g., PractitionerRole/role-456). This is useful when the role itself, not the individual, is part of the team.
3. Via Organization — an organization where the practitioner has an active role is listed as a member (e.g., Organization/downtown-clinic). This gives access to all practitioners in that organization who have the matching role.

All three paths are resolved and combined. The practitioner gains access to the union of all patients across all matching CareTeams.

Patient membership (cross-patient access)

When a patient is listed as a CareTeam.participant.member, they gain access to the CareTeam's subject patient's data. This enables scenarios like:

• Peer support programs where a patient mentor guides another patient through treatment.
• Family care scenarios where a parent-patient can view their child-patient's data.

The patient always retains access to their own compartment data in addition to the cross-patient access.

RelatedPerson membership

A RelatedPerson can only be a direct member of a CareTeam. Indirect paths (via PractitionerRole or Organization) do not apply. The related person gains access to the subject patient's data for each CareTeam where they are listed as a participant.

Nested CareTeams

CareTeams can reference other CareTeams as participants, creating a hierarchy. Fire Arrow Server resolves these nested references recursively.

{
  "resourceType": "CareTeam",
  "id": "oncology-team",
  "subject": { "reference": "Patient/patient-789" },
  "participant": [
    {
      "member": { "reference": "CareTeam/radiology-team" }
    },
    {
      "member": { "reference": "Practitioner/dr-oncologist" }
    }
  ]
}

In this example, all members of the "radiology-team" CareTeam also gain access to Patient/patient-789 through the nested reference.

Recursion depth

Nested CareTeam resolution is controlled by the max-recursion-depth configuration. Fire Arrow Server includes cycle detection to prevent infinite loops when CareTeams reference each other.

Organization participants

When an Organization is listed as a CareTeam participant, it unlocks additional access for practitioner clients. The resolved membership includes:

• Patients — the CareTeam's subject patients become accessible.
• Organization resources — the organization itself and resources linked to it (similar to LegitimateInterest's organization compartment behavior).
• Other practitioners in those organizations become visible.

This means that adding an organization to a CareTeam effectively grants all practitioners in that organization access to the CareTeam's patient data.

CareTeam participant role filtering

Validation rules can specify a care-team-role to restrict access to only those CareTeam members who hold a specific role. Roles are matched against the CareTeam.participant.role coding using the SNOMED CT system (http://snomed.info/sct).

Real-world example: Tiered CareTeam access

A care coordination platform wants to give different levels of access based on the team member's role:

• Primary care providers (SNOMED: 446050000) can read and update all clinical data.
• Care coordinators (SNOMED: 768820003) can view care plans and tasks but not detailed clinical results.

application.yaml

fire-arrow:
  authorization:
    validation-rules:
      # Primary care providers: full access
      - client-role: Practitioner
        resource: Observation
        operation: read
        validator: CareTeam
        care-team-role: "446050000"

      - client-role: Practitioner
        resource: Observation
        operation: search
        validator: CareTeam
        care-team-role: "446050000"

      - client-role: Practitioner
        resource: Condition
        operation: read
        validator: CareTeam
        care-team-role: "446050000"

      # Care coordinators: care plan and task access only
      - client-role: Practitioner
        resource: CarePlan
        operation: read
        validator: CareTeam
        care-team-role: "768820003"

      - client-role: Practitioner
        resource: Task
        operation: search
        validator: CareTeam
        care-team-role: "768820003"

In this configuration, a practitioner listed as a "Primary care provider" on the CareTeam can view observations and conditions, while a "Care coordinator" can only view care plans and tasks.

Combining with practitioner role filtering

The CareTeam validator also supports practitioner-role-system and practitioner-role-code on the validation rule, just like LegitimateInterest. When both CareTeam role filtering and practitioner role filtering are active:

1. Practitioner role filtering narrows the organizations and PractitionerRoles used for indirect CareTeam membership resolution.
2. CareTeam role filtering then further narrows which CareTeam participations are considered.

This allows combining organizational role requirements with CareTeam-specific role requirements for maximum precision.

Configuration

Validation rules

CareTeam is specified as a simple string value in the validator field:

application.yaml

fire-arrow:
  authorization:
    validation-rules:
      - client-role: Practitioner
        resource: Observation
        operation: read
        validator: CareTeam

      - client-role: RelatedPerson
        resource: Patient
        operation: read
        validator: CareTeam

Recursion depth

The maximum depth for nested CareTeam resolution is configured separately from the validation rules, under the fire-arrow.validators.care-team section:

application.yaml

fire-arrow:
  validators:
    care-team:
      max-recursion-depth: 3

Setting	Description
max-recursion-depth: 1	Only direct CareTeam references; nested CareTeams are not followed.
max-recursion-depth: 5	Default. Follows up to 5 levels of nested CareTeam references.
max-recursion-depth: N	Up to N levels. Maximum value is 10. Minimum value is 1.

Circular references are detected and safely handled. If CareTeam A references CareTeam B and CareTeam B references CareTeam A, the loop is broken automatically and a warning is logged.

Real-world scenarios

Multidisciplinary diabetes management

A patient with diabetes has a care team that includes their primary care physician, an endocrinologist from a different clinic, a dietician, and a diabetes nurse educator. Each of these practitioners is at a different organization. By creating a CareTeam resource listing all of them as participants, all practitioners gain access to the patient's clinical data (observations, conditions, care plans) through the CareTeam validator — without needing to add them to each other's organizations.

Post-discharge home care

After a hospital stay, a patient is discharged and a home care CareTeam is created with the hospital physician, a visiting nurse agency (as an organization participant), and a family caregiver (as a RelatedPerson participant). The visiting nurses from the agency can access the patient's care plan and medication list. The family caregiver can view the discharge summary and upcoming appointments.

Peer support program

In a chronic disease management program, patients who have successfully managed their condition can mentor newly diagnosed patients. The mentor patient is added as a participant on the mentee's CareTeam. Through the cross-patient access feature, the mentor can view the mentee's care plan and progress notes, while the mentee's detailed clinical data remains restricted to healthcare providers on the team.

What CareTeam membership grants access to

Once CareTeam membership is resolved, the authenticated client gets access to:

Resource category	What is accessible
CareTeam resources	The CareTeam resources the client participates in
Patients	Subject patients from all matching CareTeams
Patient compartment resources	Clinical data (observations, conditions, encounters, etc.) for accessible patients
Organizations	Organizations listed as CareTeam participants
Organization compartment resources	Resources linked to participant organizations (same as LegitimateInterest's organization compartment)
Practitioners & roles	Practitioners and PractitionerRoles in participant organizations
Tasks	Tasks for accessible patients

Performance

The CareTeam validator is resource-intensive because it must resolve CareTeam memberships, which involves searching for CareTeam resources and then extracting accessible patients, organizations, and nested CareTeams from the results.

Cache behavior

CareTeam membership resolution results are cached using the same multi-layer cache infrastructure as LegitimateInterest. Two dedicated cache layers exist for CareTeam:

• CareTeam membership cache: Caches the resolved membership (accessible patients, organizations, and CareTeam IDs) per participant reference and CareTeam role combination. Default TTL: 60 seconds.
• CareTeam practitioner membership cache: Caches the composite result of direct + indirect (via PractitionerRole and Organization) membership resolution per practitioner. This avoids re-resolving all three membership paths on repeated requests.

Cache entries are automatically invalidated when CareTeam resources are created, updated, or deleted. Changes to related resources (Patient, PractitionerRole, Organization) also trigger CareTeam cache invalidation to ensure consistency.

Cache warm-up

The first request from a given client after server startup (or after a cache eviction) triggers the full membership resolution:

1. Direct membership: Searching for CareTeam resources where the client is a participant (one database query).
2. Indirect membership (practitioners only): Resolving PractitionerRole and Organization references, then batch-searching for CareTeams where those references are participants (one additional batch query).
3. Nested CareTeam resolution: If any CareTeam references another CareTeam as a participant, loading those nested CareTeams (one query per recursion level, up to max-recursion-depth).

This warm-up period results in noticeably slower response times for the first request. Subsequent requests benefit from the cache and are significantly faster.

Scaling characteristics

Factor	Impact
Number of CareTeams the client participates in	More CareTeams means more participant entries to process during membership extraction
Number of patients across all CareTeams	Determines the size of the accessible patient set, which affects search narrowing
CareTeam nesting depth	Each level of nested CareTeams adds a database round-trip
Organization participants	When organizations are CareTeam members, all practitioners in those organizations gain indirect access, expanding the resolution scope
Practitioner indirect paths	Practitioners with many PractitionerRoles or memberships in many organizations increase the number of indirect CareTeam lookups

After cache warm-up, read operations for resources in the accessible scope add negligible overhead. Search operations require building the authorized resource set, which scales with the number of accessible patients and organizations (similar to LegitimateInterest).

Recommendations

• Keep max-recursion-depth as low as practical — each level of CareTeam nesting adds a database round-trip during resolution. The default of 5 is generous; most real-world scenarios need 1 or 2.
• Avoid deeply nested CareTeam hierarchies — prefer flat CareTeam structures where all relevant members are listed directly on the CareTeam. Nesting is useful for modeling team-of-teams scenarios but comes with a performance cost.
• Combine with LegitimateInterest strategically — use LegitimateInterest for intra-organizational access where it naturally fits, and reserve CareTeam for cross-organizational care coordination scenarios.
• Monitor cache hit rates — if you see frequent cache misses (e.g., due to frequent CareTeam mutations or a very large number of distinct client identities), consider increasing the cache max-size or ttl-seconds.