# Open Patient Record Protocol Authorization and Representation

OPRP is a backend information-exchange protocol. The requester specifies the permissions and access period it wants. The Host checks existing authorization and issues tokens for permitted access. If requested permissions or their requested duration require new patient approval, the Host initiates that approval process. How the Host obtains advance permission, chooses preauthorizable data elements, or requests new approval is its own policy. This architectural design remains evolving; the executable experimental fields are documented in [wire profile](wire-profile.md), with implementation limits in [status](implementation-status.md).

## Protocol contract and Host policy

| Required exchange contract | Host-specific behavior |
| --- | --- |
| Authenticate the requesting application and evaluate its explicitly requested permissions and access period for the patient. | Define advance authorization and applicable approval rules, including eligible data elements, maximum periods, and representative authority. |
| Initiate patient or representative approval if requested permissions require it; report issued, pending, or denied access. | Choose how approval is requested, including any login requirements, interface, and notifications. |
| Advertise supported interactions and let clients follow or check a pending request. | Operate the patient interface or integrate an existing identity and consent service. |
| Enforce the issued permissions, validity, requester binding, and current authorization status. | Choose internal policy storage, evidence verification, and applicable decision rules. |
| Distinguish the patient from a representative or other actor when relevant. | Determine and verify the actor's legal or delegated authority. |

A conforming Host need not implement a patient portal, a particular policy engine, or every example approval channel. The reference Host demonstrates several policies so interoperability can be tested across differing decision systems. Reference policy schemas are not automatically mandatory wire formats.

## Separate identity authority and tokens

Requester credentials establish who is asking. A standing policy or grant establishes what that requester may do. A short-lived JWT represents the access the Host currently permits. Record access still depends on current authorization, not just the JWT's signature and expiry.

The Host operates or designates the authorization service. Vendors request tokens from that service, not from Convey, a credential authority, or the patient directly. Independent authorities certify identities and keys; they do not decide a patient's clinical permissions.

The patient can configure standing permissions directly or adopt policies as part of a hosting agreement. The reference Host expresses requesters, record categories, operations, purposes, conditions, and duration in inspectable policies. Another Host may represent its agreements and authority differently. A vendor's verified identity never by itself authorizes unrestricted record access.

## Token request outcomes

Evaluate requested permissions individually. A single request may include both preauthorized access and access that requires a new decision. The protocol defines that conditional behavior without dictating the Host's consent policy.

| Outcome | Host behavior |
| --- | --- |
| Requested permissions are already authorized under the Host's current rules | Issue a scoped token without a new patient approval event. |
| Requested permissions require fresh patient approval | Initiate approval through the Host's chosen process and return pending status for those permissions. Do not grant them while pending. |
| The request is forbidden or authority cannot be established | Deny it. Identity validation alone cannot convert denial into approval. |
| The requester asks for expanded permissions or a longer authorized period | Evaluate the expansion separately; existing authority does not silently broaden or extend. |

The first executable profile returns the whole mixed request as pending and identifies only scopes needing fresh approval, with an expiry. It creates a durable task, deduplicates requests, and applies Host-configurable quotas. Cancellation, trusted denial and expiry are terminal. Polling reevaluates pending policy, including automatic issuance when new standing authority becomes sufficient. Actual approval channels, comprehensive abuse defense and possible partial issuance remain work before freezing the format.

Approval channels can include a mobile application, email-based interaction, an authenticated website, or an authorized representative. The Host verifies the approving actor and binds their decision to the exact request. OPRP does not require the patient to maintain a portal session. Authenticating a policy change is distinct from demanding authentication whenever an application obtains a new token.

## Requested and authorized access periods

Every request states how long access is wanted. The wire schema will define a duration or explicit end time and its start semantics. The response distinguishes the actual authorized period from the expiration of the accompanying JWT. Approval messages include both scope and duration.

| Lifetime | Meaning |
| --- | --- |
| Requested access period | The period the requester asks the Host to authorize. |
| Authorized access period | The period the Host actually approves under current authority, possibly shorter than requested. |
| Access-token lifetime | The short interval during which one JWT can be used within that approved period. |
| Refresh-credential lifetime | The interval in which a refresh credential can obtain replacement JWTs, bounded by the approved period. |

For example, a hospital EMR can be authorized for 90 days while using five-minute JWTs, and a lab application can be authorized for one day with the same short token lifetime. These are illustrative values, not prescribed limits. The Host returns the approved end time; no token or refresh credential extends access past it. Different scopes with different approved periods must be represented explicitly rather than silently sharing the longest period.

An expired authorization requires a new or extended authorization decision. That may be automatic when an applicable standing policy covers it; otherwise the Host requests patient or representative approval. Refreshing an existing token never by itself extends the authorized period.

## Refresh and current authorization

OPRP defines a refresh exchange and capability discovery. Issuing a refresh credential is a Host policy decision. It is particularly useful for mobile applications and longer-lived integrations. Authenticated backend services can instead obtain replacement tokens directly under the same bounded authorization.

A refresh credential is presented to the Host's authorization service, not used as a record-access token. It identifies an authorization and is bound to the requesting client or application instance. Refresh returns a new short-lived JWT with no additional scope or time beyond current authority. Advertise effective scope, authorization end, token expiry, and refresh expiry where applicable. The refresh credential need not itself be a JWT.

Use rotation and reuse detection together with requester binding in the reference design. Define recovery from a lost refresh response and concurrent SDK refresh calls so legitimate retries do not create unsafe replay allowances. Set an absolute expiry no later than the authorized end; a Host may also choose a shorter expiry or inactivity limit. Revoke the refresh family when its authorization ends or is withdrawn. These protections build on [OAuth security guidance](https://www.rfc-editor.org/rfc/rfc9700.html#section-4.14).

The current prototype implements bounded same-logical-ID recovery using an encrypted successor receipt and an awaited SDK persistence hook. Its restart and loss tests pass. Multiple processes sharing credentials still need coordination, and external review/secure storage remain gates. See [refresh recovery](refresh-recovery.md) for exact behavior; it is an OPRP draft extension rather than an inherited OAuth standard.

Mobile instances do not carry a vendor-wide private key or pretend to be confidential server clients. Define how instance credentials are associated with a verified application and its patient authorization, and document platform-appropriate credential storage. Refresh requests use the protected exchange and compatible instance authentication. SDKs handle expiry and renewal without unnecessary patient interaction.

Host migration reissues destination tokens and refresh credentials after reestablishing current authorization. Source credentials are not copied or implicitly valid at the new issuer. Revoked authority cannot be recovered by refresh, queue replay, or notification retries.

## Automated renewal and enforcement

When a token expires, the SDK uses the supported refresh exchange or authenticated token request to obtain a replacement within the existing authorization. The Host checks its current rules, scope, authority status, and authorized end time. No new patient approval is required solely because a JWT expires. If an extension or changed authority requires fresh approval, initiate that process and report it. Token issuance does not itself extend a grant's lifetime or satisfy an activation condition that is no longer true.

The OPRP JWT profile defines Host issuer, intended audience, requester identity, patient context, permitted actions and data scope, validity, key binding, and an opaque authorization-decision reference where applicable. It need not expose internal policy records. Exact claim names and signature encoding remain specification work. A JWT is not automatically confidential; protect sensitive authorization context using the encrypted exchange design.

The reference policy engine evaluates narrower restrictions, deny rules, representative limits, and jurisdictional constraints with explicit precedence. These are implementation and Host policy choices. The protocol requires that returned permissions accurately represent the Host's decision and that their scope is enforced. Bind tokens to their authenticated requester so possession of a copied token is insufficient.

At use and notification delivery, check current policy and representative status. Changes invalidate or reevaluate affected tokens, grants, subscriptions, and queued work. Define safe behavior for cached authorization and failures of policy or revocation services. A valid signature is necessary but does not prove ongoing permission.

## Emergency preauthorization

A patient can establish a standing policy such as limited emergency access for eligible responders. The exact record set is selected by the policy; it might contain medication and allergy information while excluding unrelated documents. It does not require patient interaction during the emergency.

The requester supplies authenticated identity, emergency purpose, and evidence or attestations required by the Host. The Host decides eligibility and conditions, issues a bounded token when authorized, and records the requester, actor when applicable, permitted scope, and decision. The reference Host also records policy version and evidence references. Patient or representative notifications follow the Host's policy; their acknowledgement is not an intrinsic protocol prerequisite for emergency issuance.

An assertion of emergency does not create a universal permission. The policy must define what evidence is sufficient and who may assert it. Any emergency disclosure supported by an external legal basis rather than the patient's policy is separately modeled in the jurisdiction profile. Avoid an unscoped break-glass bypass in the core.

## Delegation and representation

Keep the record subject, acting person, requesting application or deployment, and source of authority separate. The actor uses their own identity and keys. Patient account sharing obscures this chain and is not the delegation mechanism.

| Authority type | Source and boundaries |
| --- | --- |
| Patient-appointed delegate | An explicit patient grant permitting defined access or control, with duration and further-delegation rules. |
| Parent or legal guardian | Verified authority under applicable rules, including record-specific restrictions and changes over time. |
| Health-care power-of-attorney representative | Verified document and effective authority, including any activation conditions and limited scope. |
| Other legally authorized representative | Evidence and permitted actions defined by the applicable jurisdiction profile. |

Do not require a new patient-signed in-app grant when valid authority derives from guardianship or another applicable legal basis. Do not infer unrestricted control from a family relationship, an uploaded document, or a requester-supplied role label.

The reference authority record includes patient and actor identities, source, evidence reference, verifier, verification time, effective period, activation conditions, allowed actions, record scope, status, and audit history. Independent Hosts may use equivalent internal models. The exchange contract communicates relevant identities and permitted scope without requiring legal documents in every message. Reference guidance covers multiple representatives and incompatible instructions.

Read access, management of vendor grants, record changes, export, Host transfer, and appointing further delegates are separate permissions. A representative cannot grant permissions beyond their own authority. Reevaluate dependent grants when that authority changes; define which remain valid through another independent source of authority.

In the US profile, parental authority may have exceptions for particular care, and a health-care power of attorney may only become effective under specified conditions. Encode these boundaries through verified authority and jurisdiction rules rather than a permanent universal parent or POA flag. [HHS personal representatives](https://www.hhs.gov/hipaa/for-professionals/privacy/guidance/personal-representatives/index.html), [HHS power-of-attorney guidance](https://www.hhs.gov/hipaa/for-professionals/faq/does-having-health-care-power-attorney-allow-access-patients-medical-mental-health-records-under-hipaa/index.html)

## Standards relationship

JWT defines a token format, not a mandatory login flow. SMART Backend Services already describes autonomous access-token acquisition for preauthorized clients. OPRP can reuse relevant conventions while specifying its own patient policies, representation, encrypted messages, and authority credentials. Patient context and scope mapping require explicit definition; backend scopes must not accidentally imply unrestricted access to every patient at a Host. [JWT](https://www.rfc-editor.org/rfc/rfc7519.html), [SMART Backend Services](https://hl7.org/fhir/smart-app-launch/STU2.2/backend-services.html)

FHIR RelatedPerson and Consent are candidate data representations. They do not replace identity verification or the policy engine. Do not advertise full SMART conformance until the adopted flows and post-quantum profile have been tested against the relevant specification.

## Required early verification scenarios

1. A preauthorized application obtains and replaces a token while the patient has no active session.
2. Requested permissions that need new patient approval cause the Host to initiate approval and return pending status; only verified approval activates those permissions.
3. An eligible emergency requester receives only the preauthorized subset; an ineligible requester or expanded request is denied.
4. A parent can manage only the permitted parts of a child's record; restricted material and transfer rights remain inaccessible when excluded.
5. A conditional representative is denied before activation and permitted only within verified authority afterward.
6. Revocation or loss of representative authority prevents new tokens and affected access using existing tokens, pending queues, or notifications.
7. A delegate cannot appoint further delegates or expand application access beyond their own authority.
8. Audits distinguish patient, acting representative or staff member, application, Host decision, and authority source.
9. A mixed request for preauthorized emergency data and approval-required lab results initiates approval only for the latter and never issues lab-result permissions before approval.
10. A 90-day hospital authorization and a one-day lab authorization both issue short-lived JWTs; the approved end is reported independently of token expiry.
11. The SDK refreshes during the approved period without patient interaction, and cannot refresh past expiration or request expanded scope through refresh.
12. An extended access period triggers approval when not covered by existing authority. A Host offering a shorter period reports it explicitly.
13. Rotated refresh credentials reject unauthorized reuse, recover safely from response loss, and stop working after revocation or representative-authority changes.

Run these against synthetic policies and evidence in the first authorization milestone. Also prove that a Host requiring patient login and one issuing automatically can use the same backend token contract. Verification of real legal documents and jurisdiction-specific decision rules remains Host-specific deployment work.