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

Permission Ticket Architecture

Official URL: http://smarthealthit.org/ig/permission-tickets/ImplementationGuide/smart.permission-tickets Version: 0.1.0
Draft as of 2025-11-20 Computable Name: SmartPermissionTickets

Enabling Granular, Context-Aware Authorization in Health Networks

Executive Summary

Current interoperability standards and frameworks (SMART on FHIR, TEFCA) face a "granularity gap." Authorization flows effectively force a choice between two extremes:

  1. User-Centric friction: Relying on patients to manually log in to N different portals to authorize a single app.
  2. System-Centric rigidity: Relying on backend configurations where trusted nodes get broad, "super-user" access because defining granular rules per-patient is administratively impossible.

Permission Tickets solve this by introducing a Capability-Based Access Control model to OAuth. Instead of the Data Holder asking, "Who are you and what is your pre-configured role?", it asks, "What proof do you hold that authorizes this specific request?"

A Permission Ticket is a portable, cryptographically signed artifact. It uses standard FHIR Resources as data models to describe the Subject (Patient), the Actor (Requesting Agent), and the Context (Trigger Event), enabling precise access control without requiring realtime user interaction at the data source.

Problem Space

"N Portals" Bottleneck (Consumer Access)

In standard SMART flows, if a patient wants to aggregate their data from five different hospitals into a personal health app, they must locate five different portals, remember five usernames/passwords, and click "Approve" five times. This friction destroys adoption. Furthermore, the scopes are coarse; a user can usually only say "Yes" to everything or "No" to everything.

"All-or-Nothing" Network (Backend Services)

In B2B flows (like TEFCA Treatment or Payer exchange), Client Apps authenticate via certificates. Because it is too hard to configure specific permissions for every patient and every external partner, Data Holders often default to binary trust: if the partner is a "Trusted Node," they get access to the firehose. This is unacceptable for sensitive use cases like Research, Public Health, or Social Care.

Solution: Permission Tickets

A Permission Ticket is a JWT minted by a Trusted Issuer. It acts as a self-contained authorization grant.

Core Principles

  1. Issuer-Signed: The ticket is minted by an entity the Data Holder trusts (e.g., a Trust Broker, an Identity Verifier, or the Data Holder itself).
  2. Client-Bound: The ticket is cryptographically bound to the Client ID of the requesting application.
  3. FHIR-Native: The payload uses strict FHIR Resource structures (Patient, PractitionerRole, Organization) to define identities, making integration with existing EHR logic seamless.
  4. Zero-Interaction: The Data Holder validates the ticket signature and grants access immediately. No user login page is presented.

Authorization Flow

sequenceDiagram
    participant Trigger as Trigger Event
    participant Issuer as Trusted Issuer
    participant Client as Client App
    participant Server as Data Holder (FHIR)

    Note over Trigger, Client: 1. Context Established
    Trigger->>Issuer: Event (e.g. Referral, Case Report)
    Issuer->>Issuer: Verify Context & Identity
    Issuer->>Client: Mint Permission Ticket (JWT)
    
    Note over Client, Server: 2. Redemption
    Client->>Client: Generate Client Assertion (JWT)
    Client->>Client: Embed Ticket in Assertion
    Client->>Server: POST /token (client_credentials + assertion)
    
    Note over Server: 3. Validation
    Server->>Server: Verify Client Signature
    Server->>Server: Verify Ticket Signature (Issuer Trust)
    Server->>Server: Enforce Ticket Constraints
    Server-->>Client: Access Token (Down-scoped)
    
    Note over Client, Server: 4. Access
    Client->>Server: GET /Patient/123/Immunization
    Server-->>Client: FHIR Resources

Technical Specification

Transport: SMART Backend Services Profile

This architecture is a strict profile of SMART Backend Services (which itself profiles RFC 7523).

The key difference is the payload of the client_assertion. In standard SMART Backend Services, the assertion proves the client's identity. In this architecture, the assertion also carries the Permission Tickets as an extension claim.

Trust* Automatic Registration: Clients can be automatically registered using OpenID Federation 1.0. The client includes a trust_chain in the header of its client_assertion, allowing the Authorization Server to verify the client's metadata and trust status dynamically.
  • Client IDs MUST be URL Entity Identifiers (e.g., https://app.example.com).
  • Clients SHOULD include a trust_chain in their assertion. This allows Data Holders to verify the client's legitimacy via a common Trust Anchor without requiring manual pre-registration of every client.

The Request:

POST /token HTTP/1.1
Host: fhir.hospital.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJ... (Signed JWT containing tickets and trust_chain)
&scope=system/Patient.r
Full Client Assertion Example

Here is what the client_assertion looks like when decoded. Note the trust_chain for automatic registration and the embedded ticket_context.

Client Assertion

Header
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8",
  "trust_chain": [
    "eyJhbGciOiJFUzI1NiIs... (Signed Entity Statement for Client)",
    "eyJhbGciOiJFUzI1NiIs... (Signed Entity Statement for Intermediate)",
    "eyJhbGciOiJFUzI1NiIs... (Signed Entity Statement for Trust Anchor)"
  ]
}
Payload (Claims)
{
  "iss": "https://app.client.id",
  "sub": "https://app.client.id",
  "aud": "https://network.org/token",
  "jti": "assertion-jti-123",
  "iat": 1763678603,
  "exp": 1763678903,
  "https://smarthealthit.org/permission_tickets": [
    "eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ.eyJpc3MiOiJodHRwczovL3RydXN0LWJyb2tlci5vcmciLCJzdWIiOiJodHRwczovL2FwcC5jbGllbnQuaWQiLCJhdWQiOiJodHRwczovL25ldHdvcmsub3JnIiwidGlja2V0X2NvbnRleHQiOnsic3ViamVjdCI6eyJyZXNvdXJjZVR5cGUiOiJQYXRpZW50IiwiaWQiOiIxMjMifSwiY2FwYWJpbGl0eSI6eyJzY29wZXMiOlsicGF0aWVudC8qLnJlYWQiXX19LCJpYXQiOjE3NjM2Nzg2MDMsImV4cCI6MTc2MzY4MjIwM30.AtaAYlKjgHyhKSdkusMBrGKfmsVUDABL7yj3Vm_ihZsFpDho8DM6XqzuTrx8pnM9K9ybbAwIL4Bh6NPK4SXXPg"
  ]
}
Raw Signed JWT 
eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgiLCJ0cnVzdF9jaGFpbiI6WyJleUpoYkdjaU9pSkZVekkxTmlJcy4uLiAoU2lnbmVkIEVudGl0eSBTdGF0ZW1lbnQgZm9yIENsaWVudCkiLCJleUpoYkdjaU9pSkZVekkxTmlJcy4uLiAoU2lnbmVkIEVudGl0eSBTdGF0ZW1lbnQgZm9yIEludGVybWVkaWF0ZSkiLCJleUpoYkdjaU9pSkZVekkxTmlJcy4uLiAoU2lnbmVkIEVudGl0eSBTdGF0ZW1lbnQgZm9yIFRydXN0IEFuY2hvcikiXX0.eyJpc3MiOiJodHRwczovL2FwcC5jbGllbnQuaWQiLCJzdWIiOiJodHRwczovL2FwcC5jbGllbnQuaWQiLCJhdWQiOiJodHRwczovL25ldHdvcmsub3JnL3Rva2VuIiwianRpIjoiYXNzZXJ0aW9uLWp0aS0xMjMiLCJpYXQiOjE3NjM2Nzg2MDMsImV4cCI6MTc2MzY3ODkwMywiaHR0cHM6Ly9zbWFydGhlYWx0aGl0Lm9yZy9wZXJtaXNzaW9uX3RpY2tldHMiOlsiZXlKaGJHY2lPaUpGVXpJMU5pSXNJbXRwWkNJNkltNTJUMGRTUTNOVWVqSlJTVkZNYzJKc01GcFJYM1Y0TUhSbWVXZzFhV0YyWlMxcWRrNXpRVTVYZGpnaWZRLmV5SnBjM01pT2lKb2RIUndjem92TDNSeWRYTjBMV0p5YjJ0bGNpNXZjbWNpTENKemRXSWlPaUpvZEhSd2N6b3ZMMkZ3Y0M1amJHbGxiblF1YVdRaUxDSmhkV1FpT2lKb2RIUndjem92TDI1bGRIZHZjbXN1YjNKbklpd2lkR2xqYTJWMFgyTnZiblJsZUhRaU9uc2ljM1ZpYW1WamRDSTZleUp5WlhOdmRYSmpaVlI1Y0dVaU9pSlFZWFJwWlc1MElpd2lhV1FpT2lJeE1qTWlmU3dpWTJGd1lXSnBiR2wwZVNJNmV5SnpZMjl3WlhNaU9sc2ljR0YwYVdWdWRDOHFMbkpsWVdRaVhYMTlMQ0pwWVhRaU9qRTNOak0yTnpnMk1ETXNJbVY0Y0NJNk1UYzJNelk0TWpJd00zMC5BdGFBWWxLamdIeWhLU2RrdXNNQnJHS2Ztc1ZVREFCTDd5ajNWbV9paFpzRnBEaG84RE02WHF6dVRyeDhwbk05Szl5YmJBd0lMNEJoNk5QSzRTWFhQZyJdfQ.8UcnS_XympoOuIyIBjX3l54iaO0aNEmmbLtrbk3XGGoDdcfF-PIqZPu2KBxZbnyWXMrz9C1kwWP41XIbwF06qw

Artifact: Ticket Structure

The ticket payload is a JWT. It wraps standard FHIR JSON objects within a ticket_context claim.

{
  "iss": "https://trust-broker.org",  // Who vouches for this?
  "sub": "https://app.client.id",     // Which App can use this?
  "aud": "https://network.org",       // Where is it valid?
  "exp": 1710000000,
  
  "ticket_context": {
    // WHO is the data about? (Uses FHIR Patient shape)
    "subject": { "resourceType": "Patient", ... },

    // WHO is requesting it? (Uses FHIR Practitioner/Role/Org shapes)
    // Optional: If missing, implies the App Client is the sole actor.
    "actor": { "resourceType": "PractitionerRole", ... },

    // WHY is this allowed? (Trigger Context)
    "context": { 
      "type": { "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason", "code": "REFER" },
      "focus": { "system": "http://snomed.info/sct", "code": "49436004", "display": "Atrial fibrillation" },
      
      // Optional: Issuer-specific identifiers (e.g., Case ID, Referral ID)
      // Can be used for internal tracking or opaque tokens for the issuing server.
      "identifier": [
        { "system": "https://issuer.org/cases", "value": "CASE-123" }
      ]
    },

    // WHAT data is allowed?
    "capability": { "resources": [] }
  }
}

Downloads

Server-Side Validation

The Data Holder must perform a two-layer validation:

  1. Layer 1: Client Authentication (Standard SMART)
    • Verify the client_assertion signature using the Client's registered public key (JWK).
    • Ensure the client is registered and active.
  2. Layer 2: Ticket Validation (Permission Ticket Specific)
    • Extract the https://smarthealthit.org/extension_tickets array from the assertion.
    • For each ticket:
      • Verify Signature: Use the iss (Trust Broker) public key.
      • Verify Trust: Is this iss in the Data Holder's trusted list?
      • Verify Binding: Does ticket.sub match assertion.sub (Client ID)?
    • Grant Access: If valid, grant the requested scopes constrained by the ticket's capability rules.

Developer Documentation

This section provides technical details for developers implementing the Permission Ticket Architecture, including strict schema definitions, signing algorithms, and validation logic.

TypeScript Interfaces

The following TypeScript interfaces define the structure of the Permission Ticket and the Client Assertion. These can be used for strict type checking in your implementation.

```typescript export interface PermissionTicket { iss: string; // Issuer URL (Trust Broker) sub: string; // Client ID (App) aud: string; // Audience (Network/Data Holder) exp?: number; // Expiration Timestamp jti?: string; // Unique Ticket ID ticket_context: { subject: { type?: "match" | "reference"; resourceType?: string; id?: string; identifier?: any[]; traits?: { resourceType: "Patient"; name?: { family?: string; given?: string[] }[]; birthDate?: string; identifier?: any[]; [key: string]: any; }; reference?: string; [key: string]: any; }; actor?: { resourceType: "PractitionerRole" | "RelatedPerson" | "Organization" | "Practitioner"; name?: any; identifier?: any[]; telecom?: any[]; type?: any[]; relationship?: any[]; contained?: any[]; practitioner?: { reference: string }; organization?: { reference: string }; [key: string]: any; }; context?: { type: { system?: string; code?: string; display?: string; }; focus?: { system?: string; code?: string; display?: string; }; identifier?: any[]; }; capability: { scopes?: string[]; periods?: { start?: string; end?: string; }[]; locations?: any[]; // FHIR Address organizations?: any[]; // FHIR Organization }; }; }

export interface ClientAssertion { iss: string; // Client ID (URL) sub: string; // Client ID (URL) aud: string; // Token Endpoint URL jti: string; // Unique ID iat: number; // Issued At exp: number; // Expiration

// The Permission Ticket(s) "https://smarthealthit.org/permission_tickets": string[]; }

Signing and Validation

Signing Algorithm
  • Algorithm: ES256 (ECDSA using P-256 and SHA-256) is RECOMMENDED. RS256 is also supported.
  • Header: Must include alg and kid (Key ID) to facilitate key rotation.
  • Keys:
    • Issuer: Signs the PermissionTicket. Public keys must be exposed via a JWK Set URL (e.g., https://trust-broker.org/.well-known/jwks.json).
    • Client: Signs the ClientAssertion. Public keys must be registered with the Data Holder or exposed via JWKS.
Server-Side Validation Steps

When a Data Holder receives a token request with a client_assertion, it must perform the following checks:

  1. Validate Client Assertion:
    • Verify the signature using the Client's public key.
    • Check iss == sub == Client ID.
    • Check aud matches the Token Endpoint URL.
    • Check exp is in the future.
  2. Extract Tickets:
    • Parse the https://smarthealthit.org/extension_tickets array.
  3. Validate Each Ticket:
    • Signature: Verify the signature using the Issuer's public key (fetched from iss JWKS).
    • Trust: Verify the iss is a trusted Trust Broker.
    • Binding: Verify sub matches the Client ID from the Client Assertion.
    • Expiration: Check exp is in the future.
  4. Enforce Permissions:
    • Map ticket_context.capability to OAuth Scopes.
    • Log ticket_context.actor and ticket_context.context for audit purposes.
    • Issue an Access Token with the calculated scopes.

Catalog of Use Cases

Here are seven scenarios demonstrating how FHIR resources are used to model diverse authorization needs.

Use Case 1: Network-Mediated Patient 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: Name, DOB, Identifier).
  • Actor: None (Implicitly the App/Patient).
  • Context: None.
  • Capability: mode = read, resources = Immunization, AllergyIntolerance.

Permission Ticket Artifact

Header
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
Payload (Claims)
{
  "iss": "https://trust-broker.org",
  "sub": "https://client-app.example.com/123",
  "aud": "https://network.org",
  "ticket_context": {
    "subject": {
      "type": "match",
      "traits": {
        "resourceType": "Patient",
        "name": [
          {
            "family": "Smith",
            "given": [
              "John"
            ]
          }
        ],
        "birthDate": "1980-01-01"
      }
    },
    "capability": {
      "scopes": [
        "patient/Immunization.read",
        "patient/AllergyIntolerance.read"
      ]
    }
  },
  "iat": 1763678603,
  "exp": 1763682203
}
Raw Signed JWT 
eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ.eyJpc3MiOiJodHRwczovL3RydXN0LWJyb2tlci5vcmciLCJzdWIiOiJodHRwczovL2NsaWVudC1hcHAuZXhhbXBsZS5jb20vMTIzIiwiYXVkIjoiaHR0cHM6Ly9uZXR3b3JrLm9yZyIsInRpY2tldF9jb250ZXh0Ijp7InN1YmplY3QiOnsidHlwZSI6Im1hdGNoIiwidHJhaXRzIjp7InJlc291cmNlVHlwZSI6IlBhdGllbnQiLCJuYW1lIjpbeyJmYW1pbHkiOiJTbWl0aCIsImdpdmVuIjpbIkpvaG4iXX1dLCJiaXJ0aERhdGUiOiIxOTgwLTAxLTAxIn19LCJjYXBhYmlsaXR5Ijp7InNjb3BlcyI6WyJwYXRpZW50L0ltbXVuaXphdGlvbi5yZWFkIiwicGF0aWVudC9BbGxlcmd5SW50b2xlcmFuY2UucmVhZCJdfX0sImlhdCI6MTc2MzY3ODYwMywiZXhwIjoxNzYzNjgyMjAzfQ.8UPIGoxYMufSgzcHArSou3ZCIAU2SWrPVgitbzKqA8Qv50F18C4VB81_lCVcHn23XgxPSa0IRr5vL2qyppFGOQ

Use Case 2: Authorized Representative (Proxy)

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

Ticket Schema
  • Subject: Patient (Matched by Identifier).
  • Actor: RelatedPerson (Name, Telecom, Relationship Code).
  • Context: None.
  • Capability: mode = read, search (Full Access).

Permission Ticket Artifact

Header
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
Payload (Claims)
{
  "iss": "https://trust-broker.org",
  "sub": "https://client-app.example.com/456",
  "aud": "https://network.org",
  "ticket_context": {
    "subject": {
      "resourceType": "Patient",
      "identifier": [
        {
          "system": "https://national-mpi.net",
          "value": "pt-555"
        }
      ]
    },
    "actor": {
      "resourceType": "RelatedPerson",
      "name": [
        {
          "family": "Doe",
          "given": [
            "Jane"
          ]
        }
      ],
      "telecom": [
        {
          "system": "email",
          "value": "jane.doe@example.com"
        }
      ],
      "relationship": [
        {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
              "code": "DAU",
              "display": "Daughter"
            }
          ]
        }
      ]
    },
    "capability": {
      "scopes": [
        "patient/*.read",
        "patient/*.search"
      ]
    }
  },
  "iat": 1763678603,
  "exp": 1763682203
}
Raw Signed JWT 
eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ.eyJpc3MiOiJodHRwczovL3RydXN0LWJyb2tlci5vcmciLCJzdWIiOiJodHRwczovL2NsaWVudC1hcHAuZXhhbXBsZS5jb20vNDU2IiwiYXVkIjoiaHR0cHM6Ly9uZXR3b3JrLm9yZyIsInRpY2tldF9jb250ZXh0Ijp7InN1YmplY3QiOnsicmVzb3VyY2VUeXBlIjoiUGF0aWVudCIsImlkZW50aWZpZXIiOlt7InN5c3RlbSI6Imh0dHBzOi8vbmF0aW9uYWwtbXBpLm5ldCIsInZhbHVlIjoicHQtNTU1In1dfSwiYWN0b3IiOnsicmVzb3VyY2VUeXBlIjoiUmVsYXRlZFBlcnNvbiIsIm5hbWUiOlt7ImZhbWlseSI6IkRvZSIsImdpdmVuIjpbIkphbmUiXX1dLCJ0ZWxlY29tIjpbeyJzeXN0ZW0iOiJlbWFpbCIsInZhbHVlIjoiamFuZS5kb2VAZXhhbXBsZS5jb20ifV0sInJlbGF0aW9uc2hpcCI6W3siY29kaW5nIjpbeyJzeXN0ZW0iOiJodHRwOi8vdGVybWlub2xvZ3kuaGw3Lm9yZy9Db2RlU3lzdGVtL3YzLVJvbGVDb2RlIiwiY29kZSI6IkRBVSIsImRpc3BsYXkiOiJEYXVnaHRlciJ9XX1dfSwiY2FwYWJpbGl0eSI6eyJzY29wZXMiOlsicGF0aWVudC8qLnJlYWQiLCJwYXRpZW50Lyouc2VhcmNoIl19fSwiaWF0IjoxNzYzNjc4NjAzLCJleHAiOjE3NjM2ODIyMDN9.zsQvKRCp6R9GX17nGjPLwVMQa0vCxEHAohoiKg2zni_PhVLWc6he9Eymj2BPk941JZZAY7arSbAGwsMo1l4sRg

Use Case 3: Public Health Investigation

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

Ticket Schema
  • Subject: Patient (Matched by Hospital ID).
  • Actor: Organization (Name, Identifier, Type).
  • Context: type = PUBHLTH (Public Health), focus = Tuberculosis (SCT 56717001), identifier = Case ID.
  • Capability: scopes = patient/*.read, periods (Start Date).

Permission Ticket Artifact

Header
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
Payload (Claims)
{
  "iss": "https://hospital-a.com",
  "sub": "https://pha.gov/apps/report-client",
  "aud": "https://hospital-a.com",
  "ticket_context": {
    "subject": {
      "resourceType": "Patient",
      "id": "local-patient-123"
    },
    "actor": {
      "resourceType": "Organization",
      "name": "State Dept of Health",
      "identifier": [
        {
          "system": "urn:ietf:rfc:3986",
          "value": "https://doh.state.gov"
        }
      ],
      "type": [
        {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/organization-type",
              "code": "govt"
            }
          ]
        }
      ]
    },
    "context": {
      "type": {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
        "code": "PUBHLTH",
        "display": "Public Health"
      },
      "focus": {
        "system": "http://snomed.info/sct",
        "code": "56717001",
        "display": "Tuberculosis"
      },
      "identifier": [
        {
          "system": "https://doh.wa.gov/cases",
          "value": "CASE-2024-999"
        }
      ]
    },
    "capability": {
      "scopes": [
        "patient/*.read"
      ],
      "periods": [
        {
          "start": "2025-01-01",
          "end": "2026-01-01"
        }
      ]
    }
  },
  "iat": 1763678603,
  "exp": 1763682203
}
Raw Signed JWT 
eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ.eyJpc3MiOiJodHRwczovL2hvc3BpdGFsLWEuY29tIiwic3ViIjoiaHR0cHM6Ly9waGEuZ292L2FwcHMvcmVwb3J0LWNsaWVudCIsImF1ZCI6Imh0dHBzOi8vaG9zcGl0YWwtYS5jb20iLCJ0aWNrZXRfY29udGV4dCI6eyJzdWJqZWN0Ijp7InJlc291cmNlVHlwZSI6IlBhdGllbnQiLCJpZCI6ImxvY2FsLXBhdGllbnQtMTIzIn0sImFjdG9yIjp7InJlc291cmNlVHlwZSI6Ik9yZ2FuaXphdGlvbiIsIm5hbWUiOiJTdGF0ZSBEZXB0IG9mIEhlYWx0aCIsImlkZW50aWZpZXIiOlt7InN5c3RlbSI6InVybjppZXRmOnJmYzozOTg2IiwidmFsdWUiOiJodHRwczovL2RvaC5zdGF0ZS5nb3YifV0sInR5cGUiOlt7ImNvZGluZyI6W3sic3lzdGVtIjoiaHR0cDovL3Rlcm1pbm9sb2d5LmhsNy5vcmcvQ29kZVN5c3RlbS9vcmdhbml6YXRpb24tdHlwZSIsImNvZGUiOiJnb3Z0In1dfV19LCJjb250ZXh0Ijp7InR5cGUiOnsic3lzdGVtIjoiaHR0cDovL3Rlcm1pbm9sb2d5LmhsNy5vcmcvQ29kZVN5c3RlbS92My1BY3RSZWFzb24iLCJjb2RlIjoiUFVCSExUSCIsImRpc3BsYXkiOiJQdWJsaWMgSGVhbHRoIn0sImZvY3VzIjp7InN5c3RlbSI6Imh0dHA6Ly9zbm9tZWQuaW5mby9zY3QiLCJjb2RlIjoiNTY3MTcwMDEiLCJkaXNwbGF5IjoiVHViZXJjdWxvc2lzIn0sImlkZW50aWZpZXIiOlt7InN5c3RlbSI6Imh0dHBzOi8vZG9oLndhLmdvdi9jYXNlcyIsInZhbHVlIjoiQ0FTRS0yMDI0LTk5OSJ9XX0sImNhcGFiaWxpdHkiOnsic2NvcGVzIjpbInBhdGllbnQvKi5yZWFkIl0sInBlcmlvZHMiOlt7InN0YXJ0IjoiMjAyNS0wMS0wMSIsImVuZCI6IjIwMjYtMDEtMDEifV19fSwiaWF0IjoxNzYzNjc4NjAzLCJleHAiOjE3NjM2ODIyMDN9.Fuc3rZ1EvPjKfk0JnIsZ4iJhRxIrYrL-R5fHHmHP2Kq7oqP2mbuqi5c5scWpKH_86V_x3HarJas30jlFqF8mYw

Use Case 4: Social Care (CBO) Referral

A transactional/ad-hoc user. A Food Bank volunteer needs to update a referral status. She does not have an NPI or a user account.

Ticket Schema
  • Subject: Patient (Reference).
  • Actor: PractitionerRole (Contained Practitioner + Organization).
  • Context: type = REFER (Referral), focus = Food insecurity (SCT 733423003).
  • Capability: scopes = patient/ServiceRequest.read, patient/ServiceRequest.write, patient/Task.read, patient/Task.write.

Permission Ticket Artifact

Header
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
Payload (Claims)
{
  "iss": "https://referring-ehr.org",
  "sub": "https://foodbank.org/apps/intake",
  "aud": "https://referring-ehr.org",
  "ticket_context": {
    "subject": {
      "resourceType": "Patient",
      "reference": "Patient/123"
    },
    "actor": {
      "resourceType": "PractitionerRole",
      "contained": [
        {
          "resourceType": "Practitioner",
          "id": "p1",
          "name": [
            {
              "family": "Volunteer",
              "given": [
                "Alice"
              ]
            }
          ],
          "telecom": [
            {
              "system": "email",
              "value": "alice@foodbank.org"
            }
          ]
        },
        {
          "resourceType": "Organization",
          "id": "o1",
          "name": "Downtown Food Bank"
        }
      ],
      "practitioner": {
        "reference": "#p1"
      },
      "organization": {
        "reference": "#o1"
      }
    },
    "context": {
      "type": {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
        "code": "REFER",
        "display": "Referral"
      },
      "focus": {
        "system": "http://snomed.info/sct",
        "code": "733423003",
        "display": "Food insecurity"
      }
    },
    "capability": {
      "scopes": [
        "patient/ServiceRequest.read",
        "patient/ServiceRequest.write",
        "patient/Task.read",
        "patient/Task.write"
      ]
    }
  },
  "iat": 1763678603,
  "exp": 1763682203
}
Raw Signed JWT 
eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ.eyJpc3MiOiJodHRwczovL3JlZmVycmluZy1laHIub3JnIiwic3ViIjoiaHR0cHM6Ly9mb29kYmFuay5vcmcvYXBwcy9pbnRha2UiLCJhdWQiOiJodHRwczovL3JlZmVycmluZy1laHIub3JnIiwidGlja2V0X2NvbnRleHQiOnsic3ViamVjdCI6eyJyZXNvdXJjZVR5cGUiOiJQYXRpZW50IiwicmVmZXJlbmNlIjoiUGF0aWVudC8xMjMifSwiYWN0b3IiOnsicmVzb3VyY2VUeXBlIjoiUHJhY3RpdGlvbmVyUm9sZSIsImNvbnRhaW5lZCI6W3sicmVzb3VyY2VUeXBlIjoiUHJhY3RpdGlvbmVyIiwiaWQiOiJwMSIsIm5hbWUiOlt7ImZhbWlseSI6IlZvbHVudGVlciIsImdpdmVuIjpbIkFsaWNlIl19XSwidGVsZWNvbSI6W3sic3lzdGVtIjoiZW1haWwiLCJ2YWx1ZSI6ImFsaWNlQGZvb2RiYW5rLm9yZyJ9XX0seyJyZXNvdXJjZVR5cGUiOiJPcmdhbml6YXRpb24iLCJpZCI6Im8xIiwibmFtZSI6IkRvd250b3duIEZvb2QgQmFuayJ9XSwicHJhY3RpdGlvbmVyIjp7InJlZmVyZW5jZSI6IiNwMSJ9LCJvcmdhbml6YXRpb24iOnsicmVmZXJlbmNlIjoiI28xIn19LCJjb250ZXh0Ijp7InR5cGUiOnsic3lzdGVtIjoiaHR0cDovL3Rlcm1pbm9sb2d5LmhsNy5vcmcvQ29kZVN5c3RlbS92My1BY3RSZWFzb24iLCJjb2RlIjoiUkVGRVIiLCJkaXNwbGF5IjoiUmVmZXJyYWwifSwiZm9jdXMiOnsic3lzdGVtIjoiaHR0cDovL3Nub21lZC5pbmZvL3NjdCIsImNvZGUiOiI3MzM0MjMwMDMiLCJkaXNwbGF5IjoiRm9vZCBpbnNlY3VyaXR5In19LCJjYXBhYmlsaXR5Ijp7InNjb3BlcyI6WyJwYXRpZW50L1NlcnZpY2VSZXF1ZXN0LnJlYWQiLCJwYXRpZW50L1NlcnZpY2VSZXF1ZXN0LndyaXRlIiwicGF0aWVudC9UYXNrLnJlYWQiLCJwYXRpZW50L1Rhc2sud3JpdGUiXX19LCJpYXQiOjE3NjM2Nzg2MDMsImV4cCI6MTc2MzY4MjIwM30.g0f5v-UQOHCC_D0ll_CIFWDypfnXzFfPEtoXIKqKiKkhSqaIovLIGdIDybtwfWMD_xtiicOdrTs1KDQ69GH5eg

Use Case 5: Payer Claims Adjudication

A Payer requests clinical documents to support a specific claim.

Ticket Schema
  • Subject: Patient (Reference).
  • Actor: Organization (Payer NPI).
  • Context: type = CLMATTCH (Claim Attachment), focus = Appendectomy (SCT 80146002).
  • Capability: scopes = patient/DocumentReference.read, patient/Procedure.read.

Permission Ticket Artifact

Header
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
Payload (Claims)
{
  "iss": "https://provider.com",
  "sub": "https://payer.com/apps/claims-processor",
  "aud": "https://provider.com",
  "ticket_context": {
    "subject": {
      "resourceType": "Patient",
      "reference": "Patient/456"
    },
    "actor": {
      "resourceType": "Organization",
      "identifier": [
        {
          "system": "http://hl7.org/fhir/sid/us-npi",
          "value": "9876543210"
        }
      ],
      "name": "Blue Payer Inc"
    },
    "context": {
      "type": {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
        "code": "CLMATTCH",
        "display": "Claim Attachment"
      },
      "focus": {
        "system": "http://snomed.info/sct",
        "code": "80146002",
        "display": "Appendectomy"
      }
    },
    "capability": {
      "scopes": [
        "patient/DocumentReference.read",
        "patient/Procedure.read"
      ]
    }
  },
  "iat": 1763678603,
  "exp": 1763682203
}
Raw Signed JWT 
eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ.eyJpc3MiOiJodHRwczovL3Byb3ZpZGVyLmNvbSIsInN1YiI6Imh0dHBzOi8vcGF5ZXIuY29tL2FwcHMvY2xhaW1zLXByb2Nlc3NvciIsImF1ZCI6Imh0dHBzOi8vcHJvdmlkZXIuY29tIiwidGlja2V0X2NvbnRleHQiOnsic3ViamVjdCI6eyJyZXNvdXJjZVR5cGUiOiJQYXRpZW50IiwicmVmZXJlbmNlIjoiUGF0aWVudC80NTYifSwiYWN0b3IiOnsicmVzb3VyY2VUeXBlIjoiT3JnYW5pemF0aW9uIiwiaWRlbnRpZmllciI6W3sic3lzdGVtIjoiaHR0cDovL2hsNy5vcmcvZmhpci9zaWQvdXMtbnBpIiwidmFsdWUiOiI5ODc2NTQzMjEwIn1dLCJuYW1lIjoiQmx1ZSBQYXllciBJbmMifSwiY29udGV4dCI6eyJ0eXBlIjp7InN5c3RlbSI6Imh0dHA6Ly90ZXJtaW5vbG9neS5obDcub3JnL0NvZGVTeXN0ZW0vdjMtQWN0UmVhc29uIiwiY29kZSI6IkNMTUFUVENIIiwiZGlzcGxheSI6IkNsYWltIEF0dGFjaG1lbnQifSwiZm9jdXMiOnsic3lzdGVtIjoiaHR0cDovL3Nub21lZC5pbmZvL3NjdCIsImNvZGUiOiI4MDE0NjAwMiIsImRpc3BsYXkiOiJBcHBlbmRlY3RvbXkifX0sImNhcGFiaWxpdHkiOnsic2NvcGVzIjpbInBhdGllbnQvRG9jdW1lbnRSZWZlcmVuY2UucmVhZCIsInBhdGllbnQvUHJvY2VkdXJlLnJlYWQiXX19LCJpYXQiOjE3NjM2Nzg2MDMsImV4cCI6MTc2MzY4MjIwM30.z4CKKjc9kcZ2U7_Pa61P-Gxl8jDb9SlmGkvUkwVzwRw0pwted6drdNnfige4cpwA9wxi677s3MznbF0R4mp5_Q

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 (MRN).
  • Actor: Organization (Research Institute ID).
  • Context: type = RESCH (Biomedical Research), focus = Malignant tumor of lung (SCT 363358000).
  • Capability: scopes = patient/*.read, periods (Start/End Date).

Permission Ticket Artifact

Header
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
Payload (Claims)
{
  "iss": "https://consent-platform.org",
  "sub": "https://research.org/studies/lung-cancer/app",
  "aud": "https://hospital.com",
  "ticket_context": {
    "subject": {
      "resourceType": "Patient",
      "identifier": [
        {
          "value": "MRN-123"
        }
      ]
    },
    "actor": {
      "resourceType": "Organization",
      "name": "Oncology Research Institute",
      "identifier": [
        {
          "value": "research-org-id"
        }
      ]
    },
    "context": {
      "type": {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
        "code": "RESCH",
        "display": "Biomedical Research"
      },
      "focus": {
        "system": "http://snomed.info/sct",
        "code": "363358000",
        "display": "Malignant tumor of lung"
      }
    },
    "capability": {
      "scopes": [
        "patient/*.read"
      ],
      "periods": [
        {
          "start": "2020-01-01",
          "end": "2025-01-01"
        }
      ]
    }
  },
  "iat": 1763678603,
  "exp": 1763682203
}
Raw Signed JWT 
eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ.eyJpc3MiOiJodHRwczovL2NvbnNlbnQtcGxhdGZvcm0ub3JnIiwic3ViIjoiaHR0cHM6Ly9yZXNlYXJjaC5vcmcvc3R1ZGllcy9sdW5nLWNhbmNlci9hcHAiLCJhdWQiOiJodHRwczovL2hvc3BpdGFsLmNvbSIsInRpY2tldF9jb250ZXh0Ijp7InN1YmplY3QiOnsicmVzb3VyY2VUeXBlIjoiUGF0aWVudCIsImlkZW50aWZpZXIiOlt7InZhbHVlIjoiTVJOLTEyMyJ9XX0sImFjdG9yIjp7InJlc291cmNlVHlwZSI6Ik9yZ2FuaXphdGlvbiIsIm5hbWUiOiJPbmNvbG9neSBSZXNlYXJjaCBJbnN0aXR1dGUiLCJpZGVudGlmaWVyIjpbeyJ2YWx1ZSI6InJlc2VhcmNoLW9yZy1pZCJ9XX0sImNvbnRleHQiOnsidHlwZSI6eyJzeXN0ZW0iOiJodHRwOi8vdGVybWlub2xvZ3kuaGw3Lm9yZy9Db2RlU3lzdGVtL3YzLUFjdFJlYXNvbiIsImNvZGUiOiJSRVNDSCIsImRpc3BsYXkiOiJCaW9tZWRpY2FsIFJlc2VhcmNoIn0sImZvY3VzIjp7InN5c3RlbSI6Imh0dHA6Ly9zbm9tZWQuaW5mby9zY3QiLCJjb2RlIjoiMzYzMzU4MDAwIiwiZGlzcGxheSI6Ik1hbGlnbmFudCB0dW1vciBvZiBsdW5nIn19LCJjYXBhYmlsaXR5Ijp7InNjb3BlcyI6WyJwYXRpZW50LyoucmVhZCJdLCJwZXJpb2RzIjpbeyJzdGFydCI6IjIwMjAtMDEtMDEiLCJlbmQiOiIyMDI1LTAxLTAxIn1dfX0sImlhdCI6MTc2MzY3ODYwMywiZXhwIjoxNzYzNjgyMjAzfQ.UW4NRKvcy-OwMRmyA9FmrleVbGke3DnPiEbYZ_yQBjB7HrQUBXkW_iWcV_DBQmlSpF1x_U4UaCTlM7DA-J6RSA

Use Case 7: Provider-to-Provider Consult

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

Ticket Schema
  • Subject: Patient (Reference).
  • Actor: Practitioner (NPI).
  • Context: type = REFER (Referral), focus = Atrial fibrillation (SCT 49436004).
  • Capability: scopes = patient/*.read.

Permission Ticket Artifact

Header
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
Payload (Claims)
{
  "iss": "https://referring-ehr.org",
  "sub": "https://specialist-clinic.org/apps/referral-viewer",
  "aud": "https://referring-ehr.org",
  "ticket_context": {
    "subject": {
      "resourceType": "Patient",
      "reference": "Patient/999"
    },
    "actor": {
      "resourceType": "Practitioner",
      "identifier": [
        {
          "system": "http://hl7.org/fhir/sid/us-npi",
          "value": "1112223333"
        }
      ],
      "name": [
        {
          "family": "Heart",
          "given": [
            "A."
          ]
        }
      ]
    },
    "context": {
      "type": {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
        "code": "REFER",
        "display": "Referral"
      },
      "focus": {
        "system": "http://snomed.info/sct",
        "code": "49436004",
        "display": "Atrial fibrillation"
      }
    },
    "capability": {
      "scopes": [
        "patient/*.read"
      ]
    }
  },
  "iat": 1763678603,
  "exp": 1763682203
}
Raw Signed JWT 
eyJhbGciOiJFUzI1NiIsImtpZCI6Im52T0dSQ3NUejJRSVFMc2JsMFpRX3V4MHRmeWg1aWF2ZS1qdk5zQU5XdjgifQ.eyJpc3MiOiJodHRwczovL3JlZmVycmluZy1laHIub3JnIiwic3ViIjoiaHR0cHM6Ly9zcGVjaWFsaXN0LWNsaW5pYy5vcmcvYXBwcy9yZWZlcnJhbC12aWV3ZXIiLCJhdWQiOiJodHRwczovL3JlZmVycmluZy1laHIub3JnIiwidGlja2V0X2NvbnRleHQiOnsic3ViamVjdCI6eyJyZXNvdXJjZVR5cGUiOiJQYXRpZW50IiwicmVmZXJlbmNlIjoiUGF0aWVudC85OTkifSwiYWN0b3IiOnsicmVzb3VyY2VUeXBlIjoiUHJhY3RpdGlvbmVyIiwiaWRlbnRpZmllciI6W3sic3lzdGVtIjoiaHR0cDovL2hsNy5vcmcvZmhpci9zaWQvdXMtbnBpIiwidmFsdWUiOiIxMTEyMjIzMzMzIn1dLCJuYW1lIjpbeyJmYW1pbHkiOiJIZWFydCIsImdpdmVuIjpbIkEuIl19XX0sImNvbnRleHQiOnsidHlwZSI6eyJzeXN0ZW0iOiJodHRwOi8vdGVybWlub2xvZ3kuaGw3Lm9yZy9Db2RlU3lzdGVtL3YzLUFjdFJlYXNvbiIsImNvZGUiOiJSRUZFUiIsImRpc3BsYXkiOiJSZWZlcnJhbCJ9LCJmb2N1cyI6eyJzeXN0ZW0iOiJodHRwOi8vc25vbWVkLmluZm8vc2N0IiwiY29kZSI6IjQ5NDM2MDA0IiwiZGlzcGxheSI6IkF0cmlhbCBmaWJyaWxsYXRpb24ifX0sImNhcGFiaWxpdHkiOnsic2NvcGVzIjpbInBhdGllbnQvKi5yZWFkIl19fSwiaWF0IjoxNzYzNjc4NjAzLCJleHAiOjE3NjM2ODIyMDN9.ssl44LHzYhSjB2YSxPgPzMtFMJcwGdnH4fGWmuejRyDLrSX4llGOEeNnFFBAirDcixd3bC7tDzysDxtuSaOwfQ