Ga naar hoofdinhoud

Push authorization PA-URL API

(c) Stichting Decentrale Communicatie in de Zorg (Decozo), 2026.

Distribution of this documentation other than via the Decozo website decozo.org is not allowed, see https://drafts.decozo.org/docs/licentie (in Dutch) for more information.

This page describes the external push authorization URL (PA-URL) API.

A Push Authorization URL (PA-URL) is both an authorization primitive and the endpoint used to perform operations on the authorized source document. A recipient receives a PA-URL through a DVPA-r inbox, a referral flow, an authorization code flow, or another delivery mechanism. The recipient then calls the PA-URL directly at the source DVPA-s.

This document describes the HTTP operations that can be performed on a PA-URL. It does not define how PA-URLs are created, delivered, discovered, or registered. The PA-URL schema itself is described separately in the Decozo draft: https://drafts.decozo.org/docs/push-authorization-schema.

PA-URL as Endpoint​

The PA-URL is the endpoint. Clients MUST call the URL as received and MUST NOT rewrite, reorder, normalize, or otherwise modify the path segments of the URL.

Example PA-URL shape:

https://dvpa-s.example.test/mdlink-rc0/8f3a9c4d1e2f4567890abcdeffedcba0/r:dtype=PS%2BAMO/r:dformat=MEDEUR/bind-expiry=1705276800/expiry=1767225600

A PA-URL points to one specific source document in one specific document format. The document type and format are encoded in the PA-URL. For example, the URL above refers to a PS+AMO document in MEDEUR format.

Authentication, Binding, and Policy​

Operations on a PA-URL require authentication of the caller. The exact authentication mechanism depends on the policy and deployment context. Typical mechanisms include TLS client certificates, bearer tokens, or a combination of both.

The DVPA-s evaluates the PA-URL, the caller authentication, the requested operation, and the applicable policy before executing the operation.

A PA-URL can be bound to an authenticated party. Binding may already have happened before the URL was delivered, or it may happen on first use. After binding, subsequent use of the PA-URL is only allowed for the party that matches the binding.

If a request does not satisfy authentication, binding, or policy requirements, the DVPA-s rejects the operation.

Fetch Document​

A client retrieves the source document by making an HTTP GET request to the PA-URL.

GET {pa-url}
Authorization: Bearer {token}

The Authorization header is used when the policy requires a bearer token. Deployments may also require a TLS client certificate.

Output​

If the request is accepted, the DVPA-s returns the document bytes.

200 OK
Content-Type: MEDEUR

{document bytes}

The Content-Type response header identifies the format of the returned document. This format corresponds to the document format encoded in the PA-URL.

Fetch PIN/PSK-Protected Document​

Some PA-URLs require a PIN or pre-shared key (PSK) before the source document may be retrieved. For such URLs, the client retrieves the document by making an HTTP POST request to the PA-URL with the PSK in the JSON body.

POST {pa-url}
Content-Type: application/json
Authorization: Bearer {token}
{
  "psk": "123456"
}

Output​

If the PSK is valid and the request satisfies the applicable authentication, binding, and policy requirements, the DVPA-s returns the document bytes.

200 OK
Content-Type: MEDEUR

{document bytes}

If the PSK is invalid, the DVPA-s returns 401 Unauthorized.

Copy PA-URL​

Onward authorization is performed by requesting a copy of an existing PA-URL. The copy is a new PA-URL issued by the source DVPA-s. It points to the same source document, subject to the policy applied by the source.

A client requests a copy by making an HTTP POST request to the PA-URL with action Copy.

POST {pa-url}
Content-Type: application/json
Authorization: Bearer {token}
{
  "action": "Copy"
}

Output​

If the copy operation is allowed, the DVPA-s returns a new PA-URL.

201 Created
Content-Type: application/json
{
  "url": "https://dvpa-s.example.test/mdlink-rc0/0f4e1d2c3b4a59687766554433221100/r:dtype=PS%2BAMO/r:dformat=MEDEUR/bind-expiry=1705276800/expiry=1767225600"
}

The returned URL is a distinct authorization. Its binding and use are governed by the policy associated with that copied URL.

Create AFA URL​

An AFA URL, or address for authorization, is an inbox endpoint at the caller side where the source can later inject a PA-URL. This is used when the caller wants to authorize the source for information that the caller holds for the same patient.

A client requests an AFA URL by making an HTTP POST request to the PA-URL with action AFAURL and the system key to which the returned inbox endpoint must be bound.

POST {pa-url}
Content-Type: application/json
Authorization: Bearer {token}
{
  "action": "AFAURL",
  "systemKey": "sha256:9d2f1c0e..."
}

Input​

  • action (string) required\ Must be AFAURL.
  • systemKey (string) required\ Identifier of the caller system key to which the returned inbox endpoint should be bound. The exact format is deployment-specific.

Output​

If the AFA URL operation is allowed, the DVPA-s returns the caller-side inbox endpoint and source-side care provider metadata for the patient.

201 Created
Content-Type: application/json
{
  "afaUrl": "https://dvpa-r.example.test/inbox/1234-abcd",
  "gpInfo": {
    "gp": "Example GP Practice",
    "gpId": {
      "type": "URA",
      "id": "12345678"
    },
    "pharmacist": "Example Pharmacy",
    "pharmacistId": {
      "type": "URA",
      "id": "87654321"
    }
  }
}

Errors​

The following HTTP status codes can be used by the DVPA-s external PA-URL API:

  • 400 Bad Request\ The request body is invalid, the action is unknown, or required action input is missing.
  • 401 Unauthorized\ Authentication is missing or invalid, or a supplied PIN/PSK is invalid.
  • 403 Forbidden\ The caller is authenticated, but the requested operation is not allowed by binding or policy.
  • 404 Not Found\ The PA-URL is unknown or no longer available.
  • 500 Internal Server Error\ The DVPA-s could not process the request.

Error responses use a JSON object with an error field.

{
  "error": "Forbidden"
}

Example Flow​

The recipient has received this PA-URL:

https://dvpa-s.example.test/mdlink-rc0/8f3a9c4d1e2f4567890abcdeffedcba0/r:dtype=PS%2BAMO/r:dformat=MEDEUR/bind-expiry=1705276800/expiry=1767225600

The recipient retrieves the document:

GET /mdlink-rc0/8f3a9c4d1e2f4567890abcdeffedcba0/r:dtype=PS%2BAMO/r:dformat=MEDEUR/bind-expiry=1705276800/expiry=1767225600
Host: dvpa-s.example.test
Authorization: Bearer eyJhbGciOi...

The DVPA-s validates the PA-URL, authenticates the caller, applies binding and policy checks, and returns the document:

200 OK
Content-Type: MEDEUR

{document bytes}

If the recipient needs to delegate access onward, it requests a copy:

POST /mdlink-rc0/8f3a9c4d1e2f4567890abcdeffedcba0/r:dtype=PS%2BAMO/r:dformat=MEDEUR/bind-expiry=1705276800/expiry=1767225600
Host: dvpa-s.example.test
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...
{
  "action": "Copy"
}

The DVPA-s returns a new PA-URL:

201 Created
Content-Type: application/json
{
  "url": "https://dvpa-s.example.test/mdlink-rc0/0f4e1d2c3b4a59687766554433221100/r:dtype=PS%2BAMO/r:dformat=MEDEUR/bind-expiry=1705276800/expiry=1767225600"
}
Laatst bijgewerkt op