---
title: Organizations
description: How the organization boundary works in the Huli Public API — every resource belongs to one organization, and every API key is scoped to one organization.
nav: Concepts / Organizations
order: 1
version: v1
source: handwritten
updated: 2026-06-01
---

# 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:

```json
{
  "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](/v1/scopes)).

## Organization identity

Your organization's FHIR `Organization` resource is readable at:

<Endpoint method="GET" path="/fhir/R4/Organization/:id" />

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](/v1/concepts/rate-limiting) for details). The audit record includes the
  `organization_id`, which is the basis for per-org compliance reporting.