API docs by Redocly

PCM API (FHIR + OAuth2) (0.3.2)

Download OpenAPI specification:

License: Apache-2.0

Combined OpenAPI entry point that references the FHIR and OAuth2 specifications. The production PCM OAuth origin is https://pcm2m.health.gov.il, and the production PCM FHIR base is https://pcm2m.health.gov.il/r4; non-production deployments use their assigned environment values. Participant hosts under example.org are placeholders. Canonical, identifier-system, and other named protocol URIs remain the published identifiers. Every PCM HTTP endpoint requires mTLS, including discovery, metadata, authorization, token, introspection, and FHIR interactions. Public FHIR POST/PUT interactions use closed request projections and reject prohibited content atomically with OperationOutcome responses. MoH/PCM owns Organization.active; Data Sources expose runtime availability through the status of their currently referenced Endpoint; Service Providers control only the documented HealthcareService instance business-status transitions. For FHIR searches, authorization is a hard ceiling: every primary match must both satisfy the supplied search criteria and be authorized for the caller to read. Search filters can only narrow the authorized primary-result set. _include and _include:iterate can add only related resources that the caller is authorized to read under the same resource-visibility rules; they never widen access.

Organization

Parent, service-provider, and data-source organizations.

Search organizations

Search organizations by supported parameters. Used for discovery and retrieval, including searches by active flag or identifier.

Authorizations:
(mtlsTransportbearerAuth)
query Parameters
_id
string
identifier
string

FHIR identifier search parameter.

active
string

Search by activation status (token; true|false).

type
string

Search by Organization.type code.

partof
string
_lastUpdated
string

Standard FHIR instant search parameter on server-managed meta.lastUpdated.

_include
Array of strings (OrganizationIncludeValues)
Items Enum: "Organization:endpoint" "Organization:partof"

Include authorized Organization endpoints or parents using repeatable FHIR _include parameters. _include never widens access.

_include:iterate
Array of strings (OrganizationIncludeValues)
Items Enum: "Organization:endpoint" "Organization:partof"

Recursively include authorized Organization endpoints or parents using repeatable FHIR _include:iterate parameters. Recursive inclusion never widens access.

Responses

Response samples

Content type
application/fhir+json
Example
{}

Create Service Provider child organization

After PCM separately authorizes Service Provider expansion, creates one Service Provider child under the authenticated organization's Parent. PCM derives and validates the Parent and role, assigns the logical and PCM business identifiers and authoritative name, and returns the child. PCM manages the optional read-only redirect projection from its OAuth client registration; a supplied redirect URI or other prohibited field rejects the complete request. The interaction does not allocate an OAuth client or register a certificate. Parent and Data Source child creation are not supported.

Authorizations:
(mtlsTransportbearerAuth)
Request Body schema: application/fhir+json
required
resourceType
required
string
Value: "Organization"
id
string

Optional FHIR create metadata; ignored by PCM.

object (PCMInteractionMeta)

FHIR interaction metadata accepted in client requests. Clients may declare the applicable request profile, but PCM validates the interaction shape independently. versionId and lastUpdated, along with all other unsupported Meta business/security content, are prohibited.

name
required
string non-empty
Array of objects (Extension)

Unknown ordinary non-modifier extensions only.

Array of objects (PCMOrganizationRequestContact)

Responses

Request samples

Content type
application/fhir+json
{}

Response samples

Content type
application/fhir+json
{}

Search organizations using form parameters

Equivalent to GET /Organization with the same supported parameters, authorization ceiling, result profile, and errors.

Authorizations:
(mtlsTransportbearerAuth)
Request Body schema: application/x-www-form-urlencoded
optional
_id
string
identifier
string
active
string
type
string
partof
string
_lastUpdated
string
_include
Array of strings (OrganizationIncludeValues)
Items Enum: "Organization:endpoint" "Organization:partof"
_include:iterate
Array of strings (OrganizationIncludeValues)
Items Enum: "Organization:endpoint" "Organization:partof"

Responses

Response samples

Content type
application/fhir+json
{}

Read organization

Authorizations:
(mtlsTransportbearerAuth)
path Parameters
id
required
string

Responses

Response samples

Content type
application/fhir+json
Example
{}

Check organization existence

Authorizations:
(mtlsTransportbearerAuth)
path Parameters
id
required
string

Responses

Update organization

Used by organizations to update allowed fields depending on Organization type. Parent Organization updates are limited to contact details. Service Provider children may update contact overrides. Data Source children may update contact overrides and their own validated Endpoint linkage. MoH/PCM exclusively controls Parent and child Organization.active. Parent inactivity gates child use without rewriting the child active values. The body id must equal the URL id. The complete client-writable projection is replaced: omitted optional writable fields are removed and repeating fields replace the stored collection. Every other business element, including identifier, active, role, Parent linkage, OAuth redirect projection, and applicable-certificate inventory, is prohibited. Its presence rejects the whole update. Submitted meta.versionId and meta.lastUpdated are prohibited. Accepted updates use last-write-wins only after complete validation; If-Match and PATCH are not supported.

Authorizations:
(mtlsTransportbearerAuth)
path Parameters
id
required
string
Request Body schema: application/fhir+json
required
Any of
resourceType
required
string
Value: "Organization"
id
required
string
object (PCMInteractionMeta)

FHIR interaction metadata accepted in client requests. Clients may declare the applicable request profile, but PCM validates the interaction shape independently. versionId and lastUpdated, along with all other unsupported Meta business/security content, are prohibited.

name
required
string non-empty

Unchanged authoritative Parent name; this request does not rename it.

Array of objects (Extension)

Unknown ordinary non-modifier extensions only.

Array of objects (PCMOrganizationRequestContact)

Responses

Request samples

Content type
application/fhir+json
Example
{}

Response samples

Content type
application/fhir+json
Example
{}

Endpoint

FHIR server endpoints for data sources.

Search endpoints

Authorizations:
(mtlsTransportbearerAuth)
query Parameters
_id
string
_lastUpdated
string

Standard FHIR instant search parameter on server-managed meta.lastUpdated.

thumbprint
string^[A-Za-z0-9_-]{43}$
Example: thumbprint=AzYdwvaDPYEcNh9kZXLhKkjeo2_nO1Sx9FrqT9AxCXo

Token search on the nested thumbprint value in PCM's read-only ext-applicable-certificates inventory. A match identifies an authorized visible Endpoint whose PCM registry inventory contains the value; it does not register a certificate, prove current presentation, or declare access-token binding.

Responses

Response samples

Content type
application/fhir+json
Example
{}

Create endpoint

Creates an Endpoint owned by the authenticated Data Source. The request supplies an exact HTTPS FHIR base address and initial status active or suspended; creation as off is invalid. connectionType and payloadType are fixed request-envelope values. PCM derives managingOrganization. Identity, ownership, and certificate-inventory input is prohibited.

Authorizations:
(mtlsTransportbearerAuth)
Request Body schema: application/fhir+json
required
resourceType
required
string
Value: "Endpoint"
id
string

Optional FHIR create metadata; ignored by PCM.

object (PCMInteractionMeta)

FHIR interaction metadata accepted in client requests. Clients may declare the applicable request profile, but PCM validates the interaction shape independently. versionId and lastUpdated, along with all other unsupported Meta business/security content, are prohibited.

Array of objects (Extension)

Unknown ordinary non-modifier extensions only.

status
required
string
Enum: "active" "suspended"
required
object (PCMEndpointConnectionType)
required
Array of objects (PCMEndpointPayloadType) = 1 items
address
required
string <uri>

Responses

Request samples

Content type
application/fhir+json
{}

Response samples

Content type
application/fhir+json
{}

Search endpoints using form parameters

Equivalent to GET /Endpoint with the same supported parameters, authorization ceiling, result profile, and errors.

Authorizations:
(mtlsTransportbearerAuth)
Request Body schema: application/x-www-form-urlencoded
optional
_id
string
_lastUpdated
string
thumbprint
string^[A-Za-z0-9_-]{43}$

Token search on PCM's read-only associated-certificate inventory. Matching does not register or authorize a certificate, describe the complete trust store, prove current presentation, or declare token binding.

Responses

Request samples

Content type
application/x-www-form-urlencoded

This filter reads PCM's associated-certificate inventory. It does not register or authorize a certificate, describe the complete trust store, prove current certificate presentation, declare token binding, or widen the caller's authorized Endpoint result set.

thumbprint=AzYdwvaDPYEcNh9kZXLhKkjeo2_nO1Sx9FrqT9AxCXo

Response samples

Content type
application/fhir+json
Example
{}

Read endpoint

Authorizations:
(mtlsTransportbearerAuth)
path Parameters
id
required
string

Responses

Response samples

Content type
application/fhir+json
Example
{}

Check endpoint existence

Authorizations:
(mtlsTransportbearerAuth)
path Parameters
id
required
string

Responses

Update endpoint

Replaces the complete Data Source-writable Endpoint projection. The body id must equal the URL id. The owner controls status through active, suspended, and terminal off: active and suspended are reversible, active/suspended may become off, off cannot be restored, and same-state requests are idempotent. An address change is accepted only while the current Endpoint is suspended and immediately invalidates the old audience. A referenced Endpoint cannot be turned off; create and validate a replacement, link it from the Data Source Organization, then retire the old Endpoint. PCM derives ownership. managingOrganization, identity, certificate inventory, and every other prohibited element reject the whole request. Submitted meta.versionId and meta.lastUpdated are prohibited. Only the currently referenced active Endpoint is eligible for source-token issuance and active introspection. Suspension/off does not mutate Consent or waive reporting, and PCM management access remains available for resume/replacement. If-Match and PATCH are not supported.

Authorizations:
(mtlsTransportbearerAuth)
path Parameters
id
required
string
Request Body schema: application/fhir+json
required
resourceType
required
string
Value: "Endpoint"
id
required
string
object (PCMInteractionMeta)

FHIR interaction metadata accepted in client requests. Clients may declare the applicable request profile, but PCM validates the interaction shape independently. versionId and lastUpdated, along with all other unsupported Meta business/security content, are prohibited.

Array of objects (Extension)

Unknown ordinary non-modifier extensions only.

status
required
string
Enum: "active" "suspended" "off"
required
object (PCMEndpointConnectionType)
required
Array of objects (PCMEndpointPayloadType) = 1 items
address
required
string <uri>

Responses

Request samples

Content type
application/fhir+json
Example
{}

Response samples

Content type
application/fhir+json
{}

HealthcareService

Canonical catalog services and provider service registrations.

Search services

Search canonical catalog services and provider service registrations. Use _tag=http://pcm.fhir.health.gov.il/cs/pcm-meta-tag|catalog to search catalog definitions only, and _tag=http://pcm.fhir.health.gov.il/cs/pcm-meta-tag|instance to search organization registration/instance records only. Instance registry searches can also use organization to find registrations owned by a Service Provider, and based-on to find all registrations tied to a canonical catalog service.

Identifier searches can target either PCM HealthcareService identifier system: http://pcm.fhir.health.gov.il/identifier/pcm-healthcareservice-catalog-id for canonical catalog entries, or http://pcm.fhir.health.gov.il/identifier/pcm-healthcareservice-instance-id for provider service registrations.

Catalog search is a client catalog-discovery surface. For _tag=http://pcm.fhir.health.gov.il/cs/pcm-meta-tag|catalog, PCM returns only active/registrable catalog services; passing active=true is redundant, and active=false is not a supported way to discover pending, frozen, rejected, or cancelled catalog records.

Instance search is the client registry surface. For _tag=http://pcm.fhir.health.gov.il/cs/pcm-meta-tag|instance, omitting active returns instance registrations visible to the caller, including active instances and pending instances published for objection. active=true narrows to externally usable instances. active=false returns visible inactive instances according to the client visibility rules: pending registrations are visible for objection handling; rejected/frozen/suspended registrations are visible only to the owning Service Provider HO. Cancelled registrations remain owner-visible for audit and idempotent retries but are excluded from ordinary discovery.

Authorizations:
(mtlsTransportbearerAuth)
query Parameters
_id
string
identifier
string

FHIR identifier search parameter.

active
string

Search by activation status (token; true|false).

service-category
string

FHIR R4 search by HealthcareService.category.

service-type
string

FHIR R4 search by HealthcareService.type.

name
string

Search by HealthcareService.name.

organization
string

FHIR R4 search by HealthcareService.providedBy (instance profile only).

_tag
string

FHIR token search on meta.tag. For HealthcareService use http://pcm.fhir.health.gov.il/cs/pcm-meta-tag|catalog for catalog definitions and http://pcm.fhir.health.gov.il/cs/pcm-meta-tag|instance for organization registrations/instances.

based-on
string

Search HealthcareService instance registrations by the canonical catalog HealthcareService referenced in the basedOn extension.

pcm-business-status
string

Search by the PCM-managed business-status extension for HealthcareService or Consent.

_lastUpdated
string

Standard FHIR instant search parameter on server-managed meta.lastUpdated.

Responses

Response samples

Content type
application/fhir+json
Example
{}

Register service or request a new service

Service providers discover active catalog services first with GET /HealthcareService?_tag=http://pcm.fhir.health.gov.il/cs/pcm-meta-tag|catalog&active=true. If a suitable active canonical catalog service exists, the provider posts a minimal instance HealthcareService with the basedOn extension to register for that service. If no suitable service exists, the provider posts a full new-service registration request through the same instance flow, including service name, purpose, information buckets, history depth, access mode, access duration, clinical information, and example queries.

The calling Service Provider child Organization must be operationally active: child and Parent are active and all documented policy preconditions permit use.

Submit profiles are interaction-specific server validation profiles; their canonicals are not required in request meta.profile. Direct create requests must omit meta.tag. PCM adds the authoritative HealthcareService classification tag to each returned resource: catalog for a catalog definition and instance for a provider registration. A client-supplied meta.tag is a prohibited field and is rejected with 400 Bad Request and the ordinary validation OperationOutcome.

basedOn present means an existing catalog registration; no basedOn with a full service definition means a new-service registration request. Created/read response examples use the returned pcm-healthcareservice-instance profile.

External clients do not directly create canonical catalog services. The request shape, including whether basedOn is present, selects the create path; clients do not select it with a tag. For a valid new-service registration request, PCM creates both the canonical catalog service and the provider's organization registration with businessStatus=pending and active=false. Activation and any required review or exception handling are managed outside this FHIR operation. Clients observe the result through extension[businessStatus], HealthcareService.active, and OperationOutcome responses, not through separate public review resources.

Full service definitions require a human-readable service purpose. The public FHIR representation for that purpose is HealthcareService.extraDetails, carrying the service description/purpose ("תיאור השירות (מטרה)"). Client-supplied active, businessStatus, identifiers, ownership, or other fields outside the selected closed submit schema reject the whole request. PCM assigns the stable provider-registration business identifier using system http://pcm.fhir.health.gov.il/identifier/pcm-healthcareservice-instance-id; clients must omit identifier and meta.tag. The interaction profile canonical is not required in request meta.profile. The separate $request-catalog-update operation carries a complete proposed catalog resource, so that proposal retains its fixed catalog classification tag.

Authorizations:
(mtlsTransportbearerAuth)
Request Body schema: application/fhir+json
required
One of
resourceType
required
string
Value: "HealthcareService"
id
string

Optional FHIR create metadata; ignored by PCM.

object (PCMInteractionMeta)

FHIR interaction metadata accepted in client requests. Clients may declare the applicable request profile, but PCM validates the interaction shape independently. versionId and lastUpdated, along with all other unsupported Meta business/security content, are prohibited.

required
Array of PCMBasedOnHealthcareServiceExtension (object) or objects non-empty

Responses

Request samples

Content type
application/fhir+json
Example
{}

Response samples

Content type
application/fhir+json
Example
{}

Search services using form parameters

Equivalent to GET /HealthcareService with the same supported parameters, visibility rules, authorization ceiling, result profile, and errors.

Authorizations:
(mtlsTransportbearerAuth)
Request Body schema: application/x-www-form-urlencoded
optional
_id
string
identifier
string
active
string
service-category
string
service-type
string
name
string
organization
string
_tag
string
based-on
string
pcm-business-status
string
_lastUpdated
string

Responses

Response samples

Content type
application/fhir+json
Example
{}

Read service

Reads a HealthcareService visible to the authenticated client. Client FHIR reads may return a non-searchable pending/frozen catalog when the caller obtained its direct URL from a visible instance basedOn reference. Rejected or cancelled canonical resources outside client visibility are returned as not found. A cancelled provider instance remains readable only to its owning Service Provider for audit and idempotent retries.

Authorizations:
(mtlsTransportbearerAuth)
path Parameters
id
required
string

Responses

Response samples

Content type
application/fhir+json
Example
{}

Check service existence

Authorizations:
(mtlsTransportbearerAuth)
path Parameters
id
required
string

Responses

Update service instance business status

The owning Service Provider submits exactly one target extension[businessStatus] through the closed request schema. Runtime rules permit pending -> cancelled as withdrawal, active -> suspended, and suspended -> active|cancelled; repeating an already-achieved owner target is idempotent. Direct owner active -> cancelled, PCM/MoH-only targets, changes while frozen, and cancelled reactivation are rejected. For a coupled pending new-service request, withdrawal also cancels its linked pending canonical; withdrawal against an existing canonical cancels only the instance. A PCM/MoH freeze preserves the pre-freeze owner state (active or suspended) and restores that state when the freeze is lifted; the owner cannot change it while frozen. Suspension temporarily inactivates affected eligible Consents; resumption may restore them only after PCM revalidates every current authorization condition. Withdrawal or termination permanently inactivates the affected Consents. HealthcareService.active is prohibited in the request and derived by PCM. Every definition, identity, ownership, linkage, review, or HealthcareService classification-tag field (meta.tag) is prohibited. Submitted meta.versionId and meta.lastUpdated are also prohibited. The interaction profile canonical is not required in request meta.profile.

This operation does not accept canonical catalog changes. Non-material catalog update requests use POST /HealthcareService/{id}/$request-catalog-update. Material catalog changes must be submitted through the new-service registration flow. The body id must equal the URL id. If-Match and PATCH are not supported. An accepted transition updates that same provider-instance resource: the response retains its logical id and PCM business identifier; state names are never appended to either identity. Owner status transitions preserve the existing PCM-managed approvalWindow unchanged, including in a terminal cancelled response. The request must not include that extension. active=true if and only if businessStatus=active; pending, rejected, frozen, suspended, and cancelled resources have active=false.

Authorizations:
(mtlsTransportbearerAuth)
path Parameters
id
required
string
Request Body schema: application/fhir+json
required
resourceType
required
string
Value: "HealthcareService"
id
required
string
object (PCMInteractionMeta)

FHIR interaction metadata accepted in client requests. Clients may declare the applicable request profile, but PCM validates the interaction shape independently. versionId and lastUpdated, along with all other unsupported Meta business/security content, are prohibited.

required
Array of PCMOwnerServiceBusinessStatusExtension (object) or objects non-empty

Responses

Request samples

Content type
application/fhir+json
Example
{}

Response samples

Content type
application/fhir+json
Example
{}

Request canonical service catalog update

Submit a proposed non-material update to an existing canonical HealthcareService catalog entry for PCM/MoH review. This is a FHIR operation, not a REST update interaction: the active canonical HealthcareService is not changed by the operation response.

The request body is a FHIR Parameters resource. Parameter proposedCatalog contains the complete proposed canonical HealthcareService representation after the requested change and its id must match the operation target. Optional parameter reason carries requester rationale.

Only name, extraDetails, and extension[exampleQuery] may differ semantically from the current catalog entry; a changed name remains subject to the catalog uniqueness check. PCM rejects any known protected-field difference in category, type, information buckets or history depth, tagged details, accessMode, accessDuration, allowPatientBucketChange, identifiers, tags, lifecycle state, linkage, or any other field as material or unsupported. The outer Parameters request prohibits meta.versionId and meta.lastUpdated; the embedded complete proposedCatalog may retain both optional values copied from the retrieved canonical. PCM removes them before comparison, and neither provides optimistic concurrency. Comparison is otherwise semantic rather than raw JSON: proposal version/timestamp metadata, coding display text, representation ordering, and unknown ordinary non-modifier extensions are neutral. Unknown ordinary extensions are accepted without interpretation or a round-trip guarantee; unsupported modifier extensions reject the request. Material changes use the new-service registration flow. Ordinary canonical PUT /HealthcareService/{id} remains unsupported.

Authorizations:
(mtlsTransportbearerAuth)
path Parameters
id
required
string
Request Body schema: application/fhir+json
required
resourceType
required
string
Value: "Parameters"
id
string
object (PCMInteractionMeta)

FHIR interaction metadata accepted in client requests. Clients may declare the applicable request profile, but PCM validates the interaction shape independently. versionId and lastUpdated, along with all other unsupported Meta business/security content, are prohibited.

required
Array of PCMProposedCatalogParameter (object) or PCMRequestCatalogReasonParameter (object) [ 1 .. 2 ] items

Responses

Request samples

Content type
application/fhir+json
{}

Response samples

Content type
application/fhir+json
{
  • "resourceType": "Parameters",
  • "meta": {},
  • "parameter": [
    ]
}

Consent

Consent request creation, owned consent read/search, and owned consent deactivation. Deletion is not supported.

Search consents

Search consents by supported parameters. Use _include to return actor organizations, endpoints, and parent orgs in a single bundle.

Authorizations:
(mtlsTransportbearerAuth)
query Parameters
_id
string
identifier
string

FHIR identifier search parameter.

status
string
patient
string

Search by patient logical reference. Identifier search uses patient:identifier=system|value.

patient:identifier
string

Search Consent.patient by logical identifier, formatted as system|value.

pcm-service
string

Search by pcmService extension reference (HealthcareService instance).

pcm-business-status
string

Search by the PCM-managed business-status extension for HealthcareService or Consent.

_lastUpdated
string

Standard FHIR instant search parameter on server-managed meta.lastUpdated.

_include
Array of strings (ConsentIncludeValues)

Include authorized Consent actors using repeatable FHIR _include parameters. _include never widens access.

_include:iterate
Array of strings (ConsentIterateIncludeValues)
Items Enum: "Organization:endpoint" "Organization:partof"

Recursively include authorized Organization endpoints or parents using repeatable FHIR _include:iterate parameters. Recursive inclusion never widens access.

Responses

Response samples

Content type
application/fhir+json
Example
{}

Create consent request

Create a proposed consent request for a patient and a service provider's HealthcareService instance. The pcm-service extension must reference an existing active instance service. PCM rejects requests that omit the service, point to a canonical catalog service, or point to an inactive or otherwise unusable instance. The calling Service Provider child Organization must be operationally active: the child and Parent are active and all documented policy preconditions permit use. Token issuance later repeats Organization and service state checks, so an existing active Consent does not authorize data-source access after the Service Provider, target Data Source, service instance, or referenced catalog becomes inactive/non-usable. The accepted request shape is documented by the interaction-specific pcm-consent-submit server validation profile; its canonical is not required in request meta.profile. scope=patient-privacy, category=INFA, and the fixed legal policy are mandatory on submit. Created/read response examples use the returned pcm-consent profile. Every other Consent business element is prohibited in the request and rejects the whole request. The selected service supplies the initial requested/default access mode and maximum duration. An authorized patient decision, including an assisted or delegated flow outside this client API, may narrow continuous access to one-time and/or approve a shorter period or later shorten it. The authoritative returned Consent carries the requested mode while proposed and the effective approved mode and period after approval; it never widens or extends the service limits. POST is not idempotent. If the client cannot determine whether a request succeeded, it searches its own Consents by patient, service, and status before deciding whether to retry; a retry can create a second Consent.

Authorizations:
(mtlsTransportbearerAuth)
Request Body schema: application/fhir+json
required
resourceType
required
string
Value: "Consent"
id
string

Optional FHIR create metadata; ignored by PCM.

object (PCMInteractionMeta)

FHIR interaction metadata accepted in client requests. Clients may declare the applicable request profile, but PCM validates the interaction shape independently. versionId and lastUpdated, along with all other unsupported Meta business/security content, are prohibited.

status
required
string
Value: "proposed"
required
object (PCMConsentScope)
required
Array of objects (PCMConsentInformationAccessCategory) = 1 items
required
object (PCMLogicalPatientReference)
required
Array of objects (PCMConsentPolicy) = 1 items
required
Array of PCMConsentServiceExtension (object) or objects non-empty

Responses

Request samples

Content type
application/fhir+json
{}

Response samples

Content type
application/fhir+json
{}

Search consents using form parameters

Equivalent to GET /Consent with the same supported parameters, authorization ceiling, result profile, and errors.

Authorizations:
(mtlsTransportbearerAuth)
Request Body schema: application/x-www-form-urlencoded
optional
_id
string
identifier
string
status
string
patient
string
patient:identifier
string
pcm-service
string
pcm-business-status
string
_lastUpdated
string
_include
Array of strings (ConsentIncludeValues)
_include:iterate
Array of strings (ConsentIterateIncludeValues)
Items Enum: "Organization:endpoint" "Organization:partof"

Responses

Response samples

Content type
application/fhir+json
Example
{}

Read consent

Authorizations:
(mtlsTransportbearerAuth)
path Parameters
id
required
string

Responses

Response samples

Content type
application/fhir+json
Example
{}

Check consent existence

Authorizations:
(mtlsTransportbearerAuth)
path Parameters
id
required
string

Responses

Deactivate owned consent

Service providers may deactivate a Consent request they created by setting status=inactive. PCM FHIR API does not expose patient approval, rejection, revocation, delegation, or assisted-consent flows; those are handled outside this API. Service providers may update only consents they created; deletion is not supported. The body id must equal the URL id. The closed request contains only status=inactive, fixed scope=patient-privacy, category=INFA, and legal policy, optional ordinary unknown extensions, and an optional request-profile declaration in meta.profile. Identity, patient, service, actor, period, access-mode, business-status, and every other Consent business element are prohibited; their presence rejects the whole request. Submitted meta.versionId and meta.lastUpdated are also prohibited. Accepted updates use last-write-wins after complete transition validation; If-Match and PATCH are not supported. The returned inactive Consent retains the same logical id and PCM business identifier.

Authorizations:
(mtlsTransportbearerAuth)
path Parameters
id
required
string
Request Body schema: application/fhir+json
required
resourceType
required
string
Value: "Consent"
id
required
string
object (PCMInteractionMeta)

FHIR interaction metadata accepted in client requests. Clients may declare the applicable request profile, but PCM validates the interaction shape independently. versionId and lastUpdated, along with all other unsupported Meta business/security content, are prohibited.

status
required
string
Value: "inactive"
required
object (PCMConsentScope)
required
Array of objects (PCMConsentInformationAccessCategory) = 1 items
required
Array of objects (PCMConsentPolicy) = 1 items
Array of objects

Responses

Request samples

Content type
application/fhir+json
{}

Response samples

Content type
application/fhir+json
{}

CapabilityStatement

Server metadata and supported interactions.

Read capability statement

Returns the PCM server CapabilityStatement describing supported resources, interactions, and search parameters. Retrieval requires mTLS.

Authorizations:
mtlsTransport

Responses

Response samples

Content type
application/fhir+json
{
  • "resourceType": "CapabilityStatement",
  • "id": "pcm-capabilitystatement",
  • "url": "http://pcm.fhir.health.gov.il/CapabilityStatement/pcm-capabilitystatement",
  • "version": "0.3.2",
  • "description": "Public FHIR capabilities supported by PCM for participant onboarding data, service registration, and Consent management.",
  • "format": [
    ],
  • "software": {
    },
  • "implementation": {
    },
  • "rest": [
    ],
  • "name": "PcmCapabilityStatement",
  • "title": "PCM FHIR Capability Statement",
  • "status": "active",
  • "experimental": false,
  • "date": "2026-07-28",
  • "publisher": "PCM",
  • "kind": "instance",
  • "fhirVersion": "4.0.1"
}

SMART

SMART on FHIR OAuth2 configuration.

Read SMART on FHIR configuration

OAuth2/SMART discovery document for the PCM authorization server. Retrieval of this discovery document requires mTLS. PCM supports standard SMART App Launch v2 patient-level resource-scope syntax, including query-constrained scopes with search modifiers, chaining, and reverse chaining. user/... app-launch scopes and _filter scope constraints are not supported. PCM does not enumerate standard SMART scopes through scopes_supported and advertises no custom non-FHIR scopes.

Authorizations:
mtlsTransport

Responses

Response samples

Content type
application/json
{
  • "issuer": "https://pcm2m.health.gov.il",
  • "authorization_endpoint": "https://pcm2m.health.gov.il/authorize",
  • "token_endpoint": "https://pcm2m.health.gov.il/token",
  • "introspection_endpoint": "https://pcm2m.health.gov.il/introspect",
  • "grant_types_supported": [
    ],
  • "response_types_supported": [
    ],
  • "response_modes_supported": [
    ],
  • "token_endpoint_auth_methods_supported": [
    ],
  • "token_endpoint_auth_signing_alg_values_supported": [
    ],
  • "introspection_endpoint_auth_methods_supported": [
    ],
  • "introspection_endpoint_auth_signing_alg_values_supported": [
    ],
  • "tls_client_certificate_bound_access_tokens": false,
  • "code_challenge_methods_supported": [
    ],
  • "capabilities": [
    ]
}

OAuth2

Token issuance and introspection.

OAuth2 authorization server metadata

Returns OAuth2 authorization server metadata for the PCM issuer, including authorization, token, and introspection endpoint locations. The metadata request itself requires mTLS.

Authorizations:
mtlsTransport

Responses

Response samples

Content type
application/json
{
  • "issuer": "https://pcm2m.health.gov.il",
  • "authorization_endpoint": "https://pcm2m.health.gov.il/authorize",
  • "token_endpoint": "https://pcm2m.health.gov.il/token",
  • "introspection_endpoint": "https://pcm2m.health.gov.il/introspect",
  • "grant_types_supported": [
    ],
  • "response_types_supported": [
    ],
  • "code_challenge_methods_supported": [
    ],
  • "token_endpoint_auth_methods_supported": [
    ],
  • "token_endpoint_auth_signing_alg_values_supported": [
    ],
  • "introspection_endpoint_auth_methods_supported": [
    ],
  • "introspection_endpoint_auth_signing_alg_values_supported": [
    ],
  • "tls_client_certificate_bound_access_tokens": false
}

Start standalone SMART authorization

Starts the standalone SMART authorization-code flow. The client uses its assigned Service Provider application client_id, exact registered redirect URI, PKCE S256, and the exact PCM FHIR base as aud. The client requests the standard SMART App Launch v2 patient-level resource scopes needed by the application as one space-delimited scope value. PCM does not support user/... app-launch scopes and may grant a different or narrower scope set. The subsequent client-facing token response reports the app-launch grant, while the authoritative service-derived permissions presented to a Data Source are returned in that Data Source's active introspection response. A client assertion is not sent to this endpoint; asymmetric client authentication occurs during the code exchange. The authorization request itself still requires transport-level mTLS.

Authorizations:
mtlsTransport
query Parameters
response_type
required
string
Value: "code"
client_id
required
string

Opaque PCM-assigned OAuth client identifier for the Service Provider application.

redirect_uri
required
string <uri>

Exact registered standalone SMART redirect URI.

scope
required
string non-empty ^(?!user/)(?!.* user/)(?!.*(?:\?|&)_filter(?:...
Example: scope=patient/*.rs

Space-delimited SMART App Launch v2 patient-level resource-scope string. PCM accepts standard patient/... SMART v2 syntax and does not support user/... app-launch scopes. Query-constrained FHIR resource scopes may use search modifiers, chaining, and reverse chaining, including the experimental syntax described by SMART; _filter is not supported. URL-encode the complete parameter value so & characters inside a scope constraint are not parsed as separate authorization-request parameters. The requested scopes remain subject to client, user, service-definition, and PCM authorization policy.

state
required
string non-empty

Unpredictable client-generated value validated after redirect.

code_challenge
required
string [ 43 .. 128 ] characters
code_challenge_method
required
string
Value: "S256"
aud
required
string <uri>

Exact PCM FHIR REST API base.

Value: "https://pcm2m.health.gov.il/r4"

Responses

Response samples

Content type
application/json
{
  • "error": "invalid_request",
  • "error_description": "Missing resource parameter (RFC 8707)"
}

Issue access token

Issues an opaque access token using either the standalone SMART authorization-code exchange or a supported client-credentials token class. The endpoint requires mTLS as a transport-level policy, while OAuth2 client authentication is performed with private_key_jwt. Each request uses a fresh assertion signed with a certificate registered out of band for the opaque client_id. The assertion audience is this exact token endpoint. When one certificate is registered for the calling role/application, it is used for transport mTLS and assertion signing. If PCM registered different certificates for that client, the assertion SHOULD include cnf.x5t#S256 identifying the certificate actually presented on this mTLS connection; PCM validates a supplied value against the connection. For data source access, the client_assertion MUST include the HL7 B2B authorization extension object as profiled by PCM, including version, requester organization identity, purpose of use, consent policy, and an absolute Consent reference. PCM uses the B2B object syntax without claiming the full UDAP token-request profile. PCM issues tokens only for role/application clients mapped to operationally active Organizations. For child Organization identities, this requires the child to be active=true, the parent to be active, and all externally documented role/state preconditions to permit use. For data source access, PCM also rechecks the target Data Source Organization and parent, its currently referenced participant Endpoint, the referenced Consent, the HealthcareService instance, and the instance's canonical catalog before issuing the token. Data Source-access and presence tokens are issued only when that referenced Endpoint is active and the request's exact resource equals its current Endpoint.address; suspended and off Endpoints are ineligible and an old/replaced address is no longer an audience. Token issuance is allowed only when the relevant Organizations are operationally active, the Consent is active, and both the instance and catalog are businessStatus=active and active=true. Endpoint status does not gate PCM-management token issuance: an otherwise authorized Data Source retains management access while its Endpoint is suspended or off so it can resume or replace it. PCM issues each access token for exactly one resource server. The token request MUST contain exactly one RFC 8707 resource parameter; requests containing more than one resource parameter fail with invalid_target. Clients request one token per resource server. PCM-management and introspection-authentication bearer requests use scope=system/*.crus. Data Source-access and presence requests use their separately derived scopes and never use that management scope.

Authorizations:
mtlsTransport
Request Body schema: application/x-www-form-urlencoded
required
One of
grant_type
required
string
Value: "authorization_code"
code
required
string non-empty

Short-lived, single-use code returned by the authorization endpoint.

redirect_uri
required
string <uri>

Exact URI used in the authorization request and registered for this client.

code_verifier
required
string [ 43 .. 128 ] characters
client_assertion_type
required
string (ClientAssertionType)
Value: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
client_assertion
required
string <application/jwt> (ClientAssertion)

Fresh compact private_key_jwt assertion signed with ES256 and the key registered out of band for the opaque client ID. iss and sub equal that client ID; aud is the exact PCM OAuth endpoint receiving the assertion; iat is the issue time; exp is no more than five minutes after iat; and jti is unique. PCM resolves the verification key from the non-public client registration. The JOSE header contains exactly alg=ES256 and typ=JWT; the profile omits kid, x5c, x5t#S256, and jku from the header. When one certificate is registered for the calling role/application, it is used for mTLS and assertion signing. When PCM registered different certificates for that client, the payload SHOULD contain cnf.x5t#S256 for the certificate presented on the mTLS connection. PCM rejects a supplied value that does not match the observed mTLS certificate. This correlates client credentials and does not make the issued access token certificate-bound. A retried request uses a new assertion.

Responses

Request samples

Content type
application/x-www-form-urlencoded
Example

The client assertion is newly generated for this exchange and has iss=sub=pcm-client-hospital-a, aud equal to the exact PCM token endpoint, a unique jti, and a short expiry. The compact value uses the required ES256 header; its ExampleSignature segment is illustrative rather than a cryptographic test vector.

grant_type=authorization_code&code=v4LTC1JxW9Q2example&redirect_uri=https%3A%2F%2Fapp.hospital-a.example.org%2Fpcm%2Foauth2%2Fcallback&code_verifier=8Zp7n4mTQ2xV6cK9rB3wF5sL1yH0dJ4uN7aE6gC2iP8&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJwY20tY2xpZW50LWhvc3BpdGFsLWEiLCJzdWIiOiJwY20tY2xpZW50LWhvc3BpdGFsLWEiLCJhdWQiOiJodHRwczovL3BjbTJtLmhlYWx0aC5nb3YuaWwvdG9rZW4iLCJpYXQiOjE3MDY2NDAwMDAsImV4cCI6MTcwNjY0MDMwMCwianRpIjoiYXV0aC1jb2RlLWV4Y2hhbmdlLTAwMDEifQ.ExampleSignature

Response samples

Content type
application/json
Example

scope reports the app-launch grant returned to the client. It is not the Data Source's final enforcement scope. PCM derives the effective permissions from the applicable service definition and returns them to the Data Source through active token introspection.

{
  • "access_token": "9d984f7d-c183-49f1-9b7b-9d7426204f17",
  • "token_type": "Bearer",
  • "expires_in": 30,
  • "scope": "patient/*.rs"
}

Introspect access token

Validates a subject access token and returns its associated authorization context to the Data Source that owns the token audience. Protected with transport-level mTLS. The introspecting client can authenticate either with a 30-second bearer token whose exact resource is this introspection endpoint, or with private_key_jwt fields directly in the form body. Supplying both methods is invalid. PCM re-evaluates Organization, the target Data Source's currently referenced Endpoint, Consent, HealthcareService instance, and canonical catalog state during introspection. An active response requires that Endpoint to remain active and that the subject token audience still equal its exact current address. A token does not authorize access after the Service Provider, target Data Source, Endpoint, instance, or catalog is no longer operationally active/usable. Endpoint suspension or retirement therefore yields active=false without changing the Consent. For a one-time Consent, each approved Data Source has its own one-hour access window beginning with that Data Source's first qualifying active introspection. That window does not authorize another Data Source and is not a shared global window. Introspection returns active=false for that Data Source after its window ends. Unknown, inactive, wrong-audience, and other-Data-Source subject tokens receive the same privacy-safe {"active":false} response. A Data Source MAY cache an active introspection result only until the returned token exp. PCM currently issues source tokens with a 30-second lifetime, so the cache lasts no longer than the token's remaining lifetime and never more than 30 seconds. The Data Source MAY introspect more often, but need not call introspection again for each protected request while the unexpired result is cached; it MUST continue to enforce the cached audience, scope, context, and all other returned constraints and stop using the result at exp. Every active response includes pcm_authentication_context, recording the mTLS certificate and client-assertion signing certificate observed when the subject token was issued. This PCM-specific field is informational: the access token remains Bearer, no standard top-level cnf is returned, and the Data Source MAY compare the current protected-resource mTLS certificate with token_endpoint_mtls.x5t#S256 under its local policy.

Authorizations:
(mtlsTransportbearerAuth) mtlsTransport
Request Body schema: application/x-www-form-urlencoded
required
One of
token
required
string

Opaque subject token to introspect; distinct from the caller bearer credential.

token_type_hint
string
Value: "access_token"

Responses

Request samples

Content type
application/x-www-form-urlencoded
Example
token=2f1b8b7e-2d1a-4b0b-9e9a-9f02a7b3b6a1

Response samples

Content type
application/json
Example
{}