SMART Permission Tickets
0.1.0 - ci-build

SMART Permission Tickets, published by . This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/jmandel/smart-permission-tickets-wip/ and changes regularly. See the Directory of published versions

## Use Case Catalog

This page lists the current `ticket_type` registry for the seven core Permission Ticket use cases.

Use Case | `ticket_type` URI
--- | ---
Use Case 1: Patient Self Access | `https://smarthealthit.org/permission-ticket-type/patient-self-access-v1`
Use Case 2: Patient-Delegated Access | `https://smarthealthit.org/permission-ticket-type/patient-delegated-access-v1`
Use Case 3: Public Health Investigation | `https://smarthealthit.org/permission-ticket-type/public-health-investigation-v1`
Use Case 4: Social Care (CBO) Referral | `https://smarthealthit.org/permission-ticket-type/social-care-referral-v1`
Use Case 5: Payer Claims Adjudication | `https://smarthealthit.org/permission-ticket-type/payer-claims-adjudication-v1`
Use Case 6: Research Study | `https://smarthealthit.org/permission-ticket-type/research-study-access-v1`
Use Case 7: Provider-to-Provider Consult | `https://smarthealthit.org/permission-ticket-type/provider-consult-v1`

#### Per-Profile Constraints

The table below summarizes required and optional fields for each ticket type:

Use Case | `presenter_binding` | Requester | Context Fields | Access Dimensions
--- | --- | --- | --- | ---
UC1: Patient Self Access | Required unless self-issued presenter rule applies | — | (none) | `permissions` (required)
UC2: Patient-Delegated Access | Optional | `RelatedPerson` (required) | (none) | `permissions` (required)
UC3: Public Health | Optional | `Organization` (required) | `reportable_condition` | `permissions`, `data_period`, `data_holder_filter`
UC4: Social Care | Optional | `Organization` (required) | `concern`, `referral` | `permissions`
UC5: Payer Claims | Optional | `Organization` (required) | `service`, `claim` | `permissions`, `data_period`, `data_holder_filter`
UC6: Research | Optional | `Organization` (required) | `study` | `permissions`, `data_period`
UC7: Provider Consult | Optional | `PractitionerRole` (required) | `reason`, `consult_request` | `permissions`

#### Use Case 1: Patient Self Access

A patient uses a high-assurance Digital ID wallet to authorize an app to fetch their data from multiple hospitals.

##### Ticket Schema

- Subject: `Patient` (matched by demographics) or profile-defined `subject_identity_evidence`.
- Requester: None (self-access).
- Identity evidence: Profiles may require `subject_identity_evidence`; see Proposal 004 for app-issued tickets with embedded IAL2 evidence.
- Context: (none; `context` may be omitted or empty for this ticket type).
- Access: `permissions` with specific resource types and interactions.

#### Permission Ticket Artifact

##### Header

    {
      "alg": "ES256",
      "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
    }

##### Payload (Claims)

    {
      "iss": "https://trusted-issuer.org",
      "aud": "https://network.org",
      "exp": 1775789228,
      "jti": "uc1-4b33cc1d-0f6b-44bf-bd33-80f6d7140f3e",
      "ticket_type": "https://smarthealthit.org/permission-ticket-type/patient-self-access-v1",
      "presenter_binding": {
        "method": "jkt",
        "jkt": "JuI6ibZHcMPQICaIZ55PbXpnsudQmKt00D0BiEXNrMc"
      },
      "subject": {
        "patient": {
          "resourceType": "Patient",
          "identifier": [
            {
              "system": "http://hospital.example.org/mrn",
              "value": "A12345"
            }
          ],
          "birthDate": "1989-09-14",
          "name": [
            {
              "family": "Reyes",
              "given": [
                "Elena"
              ]
            }
          ]
        }
      },
      "access": {
        "permissions": [
          {
            "kind": "data",
            "resource_type": "AllergyIntolerance",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "Condition",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "Observation",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "MedicationRequest",
            "interactions": [
              "read",
              "search"
            ]
          }
        ],
        "data_period": {
          "start": "2021-01-01",
          "end": "2026-01-01"
        }
      },
      "iat": 1775785628
    }

Raw Signed JWT

    eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ. .X0WrebS0ryzpb5oe9937LHnJ7uM5p9FLuV-i9rVHJa6Gq7bYswlYpPwg655fq7qx_-Fapfdq4NxECS3y2r04Ig

#### Use Case 2: Patient-Delegated Access

An adult daughter accesses her elderly mother's records. The relationship is verified by a Trusted Issuer, not the Hospital.

##### Ticket Schema

- Subject: `Patient` (matched by demographics or identifier).
- Requester: `RelatedPerson` with relationship codings expressing both personal relationship and legal authority type.
- Context: (none; same as UC1 — delegation is expressed by the presence and type of `requester`)
- Access: `permissions` with specific resource types and interactions.

#### Permission Ticket Artifact

##### Header

    {
      "alg": "ES256",
      "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
    }

##### Payload (Claims)

    {
      "iss": "https://trusted-issuer.org",
      "aud": "https://network.org",
      "exp": 1775789228,
      "jti": "uc2-8c6f4ec2-4fb6-4c42-9530-6bbd11c77e49",
      "ticket_type": "https://smarthealthit.org/permission-ticket-type/patient-delegated-access-v1",
      "presenter_binding": {
        "method": "jkt",
        "jkt": "JuI6ibZHcMPQICaIZ55PbXpnsudQmKt00D0BiEXNrMc"
      },
      "subject": {
        "patient": {
          "resourceType": "Patient",
          "identifier": [
            {
              "system": "https://national-mpi.net",
              "value": "pt-555"
            }
          ],
          "birthDate": "1948-06-15",
          "name": [
            {
              "family": "Reyes",
              "given": [
                "Maria"
              ]
            }
          ]
        }
      },
      "requester": {
        "resourceType": "RelatedPerson",
        "relationship": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                "code": "DAU",
                "display": "daughter"
              }
            ]
          },
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
                "code": "HPOWATT",
                "display": "healthcare power of attorney"
              }
            ]
          }
        ],
        "name": [
          {
            "family": "Reyes",
            "given": [
              "Elena"
            ]
          }
        ]
      },
      "access": {
        "permissions": [
          {
            "kind": "data",
            "resource_type": "Condition",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "Immunization",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "MedicationRequest",
            "interactions": [
              "read",
              "search"
            ]
          }
        ]
      },
      "iat": 1775785628
    }

Raw Signed JWT

    eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ. .jIKgBwowW5RUeO74oDN557e_rg7NeO_GYDtfbRufReTNvVIO2VoMnOyyljdvu2o1r5Lp6H0Ms8Uu1tN0czD_Vw

#### Use Case 3: Public Health Investigation

A Hospital creates a Case Report. The Public Health Agency (PHA) uses a ticket to query for follow-up data.

##### Ticket Schema

- Subject: `Patient` (matched by demographics or identifier).
- Requester: `Organization` (public health agency).
- Context: `reportable_condition` (coded condition).
- Access: `permissions`, optional `data_period`, `data_holder_filter`, `sensitive_data`.

#### Permission Ticket Artifact

##### Header

    {
      "alg": "ES256",
      "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
    }

##### Payload (Claims)

    {
      "iss": "https://issuer.state.example.gov",
      "aud": "https://network.org",
      "exp": 1775957430,
      "jti": "uc3-16ff62cf-2d2d-4b30-8c86-6a13d7ab7d16",
      "ticket_type": "https://smarthealthit.org/permission-ticket-type/public-health-investigation-v1",
      "presenter_binding": {
        "method": "trust_framework_client",
        "trust_framework": "https://state.example.gov/trust-framework/public-health",
        "framework_type": "udap",
        "entity_uri": "https://state.example.gov/organizations/epi-unit"
      },
      "subject": {
        "patient": {
          "resourceType": "Patient",
          "identifier": [
            {
              "system": "http://hospital.example.org/mrn",
              "value": "M445566"
            }
          ],
          "birthDate": "1978-02-21",
          "name": [
            {
              "family": "Carter",
              "given": [
                "Monica"
              ]
            }
          ]
        }
      },
      "requester": {
        "resourceType": "Organization",
        "identifier": [
          {
            "system": "urn:ietf:rfc:3986",
            "value": "https://state.example.gov/organizations/epi-unit"
          }
        ],
        "name": "State Epidemiology Unit"
      },
      "access": {
        "permissions": [
          {
            "kind": "data",
            "resource_type": "Condition",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "Observation",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "DiagnosticReport",
            "interactions": [
              "read",
              "search"
            ]
          }
        ],
        "data_period": {
          "start": "2025-12-01",
          "end": "2026-06-01"
        },
        "data_holder_filter": [
          {
            "kind": "jurisdiction",
            "address": {
              "country": "US",
              "state": "TX"
            }
          }
        ],
        "sensitive_data": "include"
      },
      "context": {
        "reportable_condition": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "840539006",
              "display": "Disease caused by severe acute respiratory syndrome coronavirus 2 (disorder)"
            }
          ]
        }
      },
      "iat": 1775953830
    }

Raw Signed JWT

    eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ. .M_viuaqcGdIVyRfrdXaWZ6-HIFkDMEKStxbXJoz_is1CJwHKmLwbwzrGUemAqxRk99ryTjQwl5RLJVarS-GpaQ

#### Use Case 4: Social Care (CBO) Referral

A community-based organization needs to access referral-related data. A Food Bank volunteer needs to update a referral status.

##### Ticket Schema

- Subject: `Patient` (matched by demographics or identifier).
- Requester: `Organization` (social care hub).
- Context: `concern` (coded concern), `referral` (ServiceRequest).
- Access: `permissions` with specific resource types and interactions.

#### Permission Ticket Artifact

##### Header

    {
      "alg": "ES256",
      "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
    }

##### Payload (Claims)

    {
      "iss": "https://issuer.example.org",
      "aud": "https://network.org",
      "exp": 1775957430,
      "jti": "uc4-0d0f7272-2d85-49ef-8c39-d4a8e8d8a7f2",
      "ticket_type": "https://smarthealthit.org/permission-ticket-type/social-care-referral-v1",
      "presenter_binding": {
        "method": "trust_framework_client",
        "trust_framework": "https://smarthealthit.org/trust-frameworks/reference-demo-well-known",
        "framework_type": "well-known",
        "entity_uri": "https://aco.example.org/entities/social-care-hub"
      },
      "subject": {
        "patient": {
          "resourceType": "Patient",
          "identifier": [
            {
              "system": "http://hospital.example.org/mrn",
              "value": "S778899"
            }
          ],
          "birthDate": "1963-11-03",
          "name": [
            {
              "family": "Nguyen",
              "given": [
                "Linh"
              ]
            }
          ]
        }
      },
      "requester": {
        "resourceType": "Organization",
        "identifier": [
          {
            "system": "urn:ietf:rfc:3986",
            "value": "https://aco.example.org/entities/social-care-hub"
          }
        ],
        "name": "Community Social Care Hub"
      },
      "access": {
        "permissions": [
          {
            "kind": "data",
            "resource_type": "ServiceRequest",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "Condition",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "Observation",
            "interactions": [
              "read",
              "search"
            ]
          }
        ],
        "sensitive_data": "exclude"
      },
      "context": {
        "concern": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "733423003",
              "display": "Food insecurity"
            }
          ]
        },
        "referral": {
          "resourceType": "ServiceRequest",
          "identifier": [
            {
              "system": "http://issuer.example.org/referrals",
              "value": "REF-1001"
            }
          ],
          "status": "active",
          "intent": "order"
        }
      },
      "iat": 1775953830
    }

Raw Signed JWT

    eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ. .p4czU9oGIwMBDSDArUHBAcpRBflM3EW1paJrXkwEFlmY-psK8zUW2bP5U4xdcn_F-khBM27q4PgvF79Uwyd2IQ

#### Use Case 5: Payer Claims Adjudication

A Payer requests clinical documents to support a specific claim.

##### Ticket Schema

- Subject: `Patient` (matched by demographics or identifier).
- Requester: `Organization` (Payer).
- Context: `service` (coded service), `claim` (Claim resource).
- Access: `permissions`, optional `data_period`, `data_holder_filter`.

#### Permission Ticket Artifact

##### Header

    {
      "alg": "ES256",
      "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
    }

##### Payload (Claims)

    {
      "iss": "https://issuer.example.org",
      "aud": "https://network.org",
      "exp": 1775957430,
      "jti": "uc5-9096d8d2-3627-45ee-8ea2-5e5a0ab51b7b",
      "ticket_type": "https://smarthealthit.org/permission-ticket-type/payer-claims-adjudication-v1",
      "presenter_binding": {
        "method": "trust_framework_client",
        "trust_framework": "https://payer.example.org/trust-framework",
        "framework_type": "udap",
        "entity_uri": "https://payer.example.org/entities/claims-ops"
      },
      "subject": {
        "patient": {
          "resourceType": "Patient",
          "identifier": [
            {
              "system": "http://hospital.example.org/mrn",
              "value": "C112233"
            }
          ],
          "birthDate": "1954-07-19",
          "name": [
            {
              "family": "Johnson",
              "given": [
                "Amelia"
              ]
            }
          ]
        }
      },
      "requester": {
        "resourceType": "Organization",
        "identifier": [
          {
            "system": "urn:ietf:rfc:3986",
            "value": "https://payer.example.org/entities/claims-ops"
          }
        ],
        "name": "Acme Health Plan Claims Operations"
      },
      "access": {
        "permissions": [
          {
            "kind": "data",
            "resource_type": "Claim",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "ExplanationOfBenefit",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "DocumentReference",
            "interactions": [
              "read",
              "search"
            ]
          }
        ],
        "data_period": {
          "start": "2025-01-01",
          "end": "2025-12-31"
        },
        "data_holder_filter": [
          {
            "kind": "organization",
            "organization": {
              "resourceType": "Organization",
              "identifier": [
                {
                  "system": "http://hl7.org/fhir/sid/us-npi",
                  "value": "1234567893"
                }
              ],
              "name": "General Hospital"
            }
          }
        ],
        "sensitive_data": "exclude"
      },
      "context": {
        "service": {
          "coding": [
            {
              "system": "http://www.ama-assn.org/go/cpt",
              "code": "99214",
              "display": "Office or other outpatient visit"
            }
          ]
        },
        "claim": {
          "resourceType": "Claim",
          "identifier": [
            {
              "system": "http://payer.example.org/claims",
              "value": "CLM-884422"
            }
          ],
          "status": "active",
          "use": "claim"
        }
      },
      "iat": 1775953830
    }

Raw Signed JWT

    eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ. .a4OMMFopHxQtx6Kc-RG3o4ArLFUoWCypunkURdTfidcPYtKMD4qMiMLdjtwWCy63w-GO3f5SinG9_GPrsuJFjg

#### Use Case 6: Research Study

A patient consents to a study. The ticket proves consent exists without requiring the researcher to be a "user" at the hospital.

##### Ticket Schema

- Subject: `Patient` (matched by demographics or identifier).
- Requester: `Organization` (research institute).
- Context: `study` (ResearchStudy resource).
- Access: `permissions`, optional `data_period`, `sensitive_data`.

#### Permission Ticket Artifact

##### Header

    {
      "alg": "ES256",
      "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
    }

##### Payload (Claims)

    {
      "iss": "https://issuer.example.org",
      "aud": "https://network.org",
      "exp": 1775957430,
      "jti": "uc6-b5774e14-a020-46f2-94d3-2bb95b7ac4af",
      "ticket_type": "https://smarthealthit.org/permission-ticket-type/research-study-access-v1",
      "presenter_binding": {
        "method": "trust_framework_client",
        "trust_framework": "https://research.example.org/trust-framework",
        "framework_type": "udap",
        "entity_uri": "https://research.example.org/entities/study-team-204"
      },
      "subject": {
        "patient": {
          "resourceType": "Patient",
          "identifier": [
            {
              "system": "http://hospital.example.org/mrn",
              "value": "R445500"
            }
          ],
          "birthDate": "1970-05-30",
          "name": [
            {
              "family": "Lopez",
              "given": [
                "Marina"
              ]
            }
          ]
        }
      },
      "requester": {
        "resourceType": "Organization",
        "identifier": [
          {
            "system": "urn:ietf:rfc:3986",
            "value": "https://research.example.org/entities/study-team-204"
          }
        ],
        "name": "Study Team 204"
      },
      "access": {
        "permissions": [
          {
            "kind": "data",
            "resource_type": "Condition",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "Observation",
            "interactions": [
              "read",
              "search"
            ]
          }
        ],
        "data_period": {
          "start": "2024-01-01",
          "end": "2026-12-31"
        },
        "sensitive_data": "exclude"
      },
      "context": {
        "study": {
          "resourceType": "ResearchStudy",
          "identifier": [
            {
              "system": "http://research.example.org/studies",
              "value": "STUDY-204"
            }
          ],
          "status": "active",
          "title": "Diabetes Outcomes Registry"
        }
      },
      "iat": 1775953830
    }

Raw Signed JWT

    eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ. .oViHUuZP1BxzbXoApdK4g4PrOhKKGBh2p4NkA5BZnkzhTmbbdnj3bgPCS9A0KOgH_lJJsk7gmWlVrbBCKYSJNg

#### Use Case 7: Provider-to-Provider Consult

A Specialist (Practitioner) requests data from a Referring Provider.

##### Ticket Schema

- Subject: `Patient` (matched by demographics or identifier).
- Requester: `PractitionerRole` (specialist role).
- Context: `reason` (coded reason), `consult_request` (ServiceRequest).
- Access: `permissions` with specific resource types and interactions.

#### Permission Ticket Artifact

##### Header

    {
      "alg": "ES256",
      "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
    }

##### Payload (Claims)

    {
      "iss": "https://issuer.example.org",
      "aud": "https://network.org",
      "exp": 1775957430,
      "jti": "uc7-d6927f7f-74c8-4b1b-a7a5-7f4e6d99390a",
      "ticket_type": "https://smarthealthit.org/permission-ticket-type/provider-consult-v1",
      "presenter_binding": {
        "method": "trust_framework_client",
        "trust_framework": "https://smarthealthit.org/trust-frameworks/reference-demo-well-known",
        "framework_type": "well-known",
        "entity_uri": "https://hospital.example.org/entities/cardiology-group"
      },
      "subject": {
        "patient": {
          "resourceType": "Patient",
          "identifier": [
            {
              "system": "http://hospital.example.org/mrn",
              "value": "K667788"
            }
          ],
          "birthDate": "1981-03-08",
          "name": [
            {
              "family": "Thomas",
              "given": [
                "Jared"
              ]
            }
          ]
        }
      },
      "requester": {
        "resourceType": "PractitionerRole",
        "code": [
          {
            "coding": [
              {
                "system": "http://snomed.info/sct",
                "code": "17561000",
                "display": "Cardiologist"
              }
            ]
          }
        ]
      },
      "access": {
        "permissions": [
          {
            "kind": "data",
            "resource_type": "Condition",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "Observation",
            "interactions": [
              "read",
              "search"
            ]
          },
          {
            "kind": "data",
            "resource_type": "DiagnosticReport",
            "interactions": [
              "read",
              "search"
            ]
          }
        ],
        "sensitive_data": "exclude"
      },
      "context": {
        "reason": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "53741008",
              "display": "Coronary arteriosclerosis"
            }
          ]
        },
        "consult_request": {
          "resourceType": "ServiceRequest",
          "identifier": [
            {
              "system": "http://issuer.example.org/consults",
              "value": "CONSULT-7788"
            }
          ],
          "status": "active",
          "intent": "order"
        }
      },
      "iat": 1775953830
    }

Raw Signed JWT

    eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ. .Dbbb12BtN3CN12KaApwmPZkCs_1xNkuHgfs9xl1kFqAl2gyICv9RHPfH7EEVy2oZV0jFRQcMx0tmsGDTGFHPSQ