Organizations

Every resource in the Huli Public API — Patient, Appointment, Encounter, Observation, Practitioner, Organization — belongs to exactly one organization. The organization is the security boundary.

#How it works

When you authenticate (via any of the three modes — admin bearer, SMART backend services, or interactive OAuth), the resulting access token carries an organization_id claim. All resource access is automatically scoped to that organization. There is no way to read or write across organizations with a single token.

An API key created in Practice Settings is bound to the organization that admin belongs to. A SMART backend services client assertion is verified against an api_key row that also carries an organization_id. An interactive OAuth token carries the organization the authenticated user belongs to.

#Cross-organization access

Attempting to read a resource that belongs to a different organization returns:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "forbidden",
      "diagnostics": "HPB-00104: Insufficient scope"
    }
  ]
}

HPB-00104 covers both missing-scope and cross-organization violations. If you receive this on a resource you believe your token should reach, verify:

1. The resource ID belongs to your organization.
2. The token was issued for the same organization as the resource.
3. The token includes the scope required for the operation (e.g., system/Patient.rs for reads — see Scopes).

#Organization identity

Your organization's FHIR Organization resource is readable at:

The id is the UUID visible in Practice Settings and returned as managingOrganization.reference on Patient resources. It is stable and does not change.

#Implications for integrations

• Single-organization integrations (one API key, one organization): the organization model imposes no additional complexity. Every call works within your org.
• Multi-organization integrations (a partner serving multiple Huli organizations): you need one API key per organization. There is no cross-organization token or admin-level key that spans organizations. This is by design — it constrains PHI access to explicitly authorized integrations per org.
• Audit: every authenticated request writes an audit record (see Rate Limiting for details). The audit record includes the organization_id, which is the basis for per-org compliance reporting.