13.3. Relying Party Endpoints¶

The Relying Party MUST expose a comprehensive set of endpoints to support the complete IT-Wallet ecosystem, including both remote and proximity presentation flows.

13.3.1. Remote Flow Endpoints¶

13.3.2. Relying Party Remote Flow Endpoints¶

The Relying Party MUST expose a set of endpoints to support remote presentation flows as defined in OpenID4VP 1.0. These endpoints enable secure credential verification, trust establishment, and user authentication for cross-device and same-device interaction patterns.

Note

Tests related to Relying Party remote flow endpoints are defined in the remote presentation test matrix (Remote Credential Verifier Test Matrix).

13.3.3. Federation Endpoint¶

The Relying Party MUST provide its Entity Configuration through the /.well-known/openid-federation endpoint, according to Section trust:Entity Configuration. This endpoint enables trust establishment and discovery of the Relying Party's capabilities.

Technical details are provided in Section Relying Party Entity Configuration.

13.3.4. OpenID4VP Remote Flow Endpoints¶

The following endpoints are required for OpenID4VP 1.0 remote presentation flows as described in Remote Flow. These endpoints support both Same Device and Cross Device flows:

13.3.4.1. Request URI Endpoint¶

The Request URI Endpoint is where the Relying Party provides the signed Request Object to the Wallet Instance. This endpoint supports both GET and POST methods as defined in the OpenID4VP 1.0 specification.

For detailed implementation requirements, see remote-flow:Request URI Endpoint and Request URI Request.

13.3.4.2. Response URI Endpoint¶

The Response URI Endpoint receives the Authorization Response from the Wallet Instance containing the Verifiable Presentation. This endpoint processes the presentation and validates the credentials.

For detailed implementation requirements, see Authorization Response and Relying Party Response.

13.3.4.3. Status Endpoint (Optional)¶

The Status Endpoint is an optional endpoint that allows the user-agent to monitor the progress of the presentation flow. This endpoint is particularly useful for Same Device flows where the user-agent needs to know when the Wallet Instance has completed the presentation.

For detailed implementation requirements, see Status Endpoint and Status Endpoint Errors.

13.3.5. User Data Management Endpoints¶

The following endpoint supports user data management and privacy compliance requirements for remote flows:

13.3.5.1. Relying Party Erasure Endpoint¶

The Erasure Endpoint, which is described in Relying Party Metadata, allows Wallet Instances to request deletion of attributes presented to the Relying Party. The Relying Party MUST request User authentication before proceeding with the attribute deletion.

13.3.5.2. Erasure Request¶

The Erasure Request MUST be a GET request to the Erasure Endpoint. The Wallet Instance MUST also support a call back mechanism which enables the User-Agent to notify the Wallet Instance (and thus the User) once the Erasure Response is returned.

Below is a non-normative example of an Erasure Request where the call back URL is passed as a query parameter.

GET /erasure-endpoint?callback_url=https://wallet-instance/erasure_response HTTP/1.1
Host: relying-party.example.org

13.3.5.3. Erasure Response¶

If the deletion of all attributes bound to the User have been successful, the Erasure Response MUST return a 204 HTTP status code.

If instead the attributes deletion procedure fails due any circumstances, the Relying Party MUST return an error response with application/json as the content type and MUST include the following parameters:

error: The error code.

error_description: Text in human-readable form providing further details to clarify the nature of the error encountered.

The following table lists the HTTP Status Codes and related error codes that MUST be supported for the error response:

Status Code	Error Code	Description
`400 Bad Request`	`bad_request`	The request is malformed, missing required parameters (e.g., header parameters or integrity assertion), or includes invalid and unknown parameters.
`401 Unauthorized`	`unauthorized`	The request could not be fulfilled due to invalid authentication by the User.
`500 Internal Server Error`	`server_error`	The request cannot be fulfilled because the Erasure Endpoint encountered an internal problem. (RFC 6749#section-4.1.2.1).
`503 Service Unavailable`	`temporarily_unavailable`	The request cannot be fulfilled because the Erasure Endpoint is temporarily unavailable (e.g., due to maintenance or overload). (RFC 6749#section-4.1.2.1).

The following is an example of an error response from Erasure Endpoint:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
 "error": "server_error",
 "error_description": "The request cannot be fulfilled due to an internal server error."
}

Upon receiving an error response, the Wallet Instance which made the Erasure Request MUST inform the User of the error condition in an appropriate manner.

13.3.6. Security Considerations¶

All Relying Party endpoints MUST implement appropriate security measures:

HTTPS Only: All endpoints MUST be accessible only over HTTPS
Endpoint Mix-up Protection: Endpoint URLs MUST be attested by trusted third parties through the Trust Chain
Input Validation: All endpoints MUST validate input parameters and reject malformed requests
Rate Limiting: Endpoints SHOULD implement rate limiting to prevent abuse
Audit Logging: All endpoint interactions SHOULD be logged for security monitoring

For detailed security requirements, see remote-flow:Security Considerations and the relevant test cases in Remote Credential Verifier Test Matrix.

13.3.7. Implementation Notes¶

The specific implementation details for most endpoints are left to the Relying Party's discretion
Endpoints MUST comply with the OpenID4VP 1.0 specification for remote flows
Proximity flow endpoints MUST support the lifecycle management of Verifier Apps
All endpoints MUST be discoverable through the Relying Party's Entity Configuration
Error responses MUST follow the standard HTTP status codes and include appropriate error descriptions

For comprehensive implementation guidance, refer to the individual endpoint sections and the test matrices for validation requirements.

13.3.8. Relying Party Provider Backend Endpoints¶

13.3.9. Relying Party Provider Backend Endpoints¶

The Relying Party MUST expose a set of endpoints for handling the lifecycle of Verifier Apps that use a remote backend service provided by their Relying Party Provider Backend. These endpoints support proximity presentation flows by providing nonce generation, hardware key registration, integrity validation, and Access Certificate issuance. The specific implementation details are left to the Relying Party's discretion.

Note

Tests related to Relying Party endpoints are defined in the remote presentation test matrix (Remote Credential Verifier Test Matrix) and proximity presentation test matrix (Proximity Credential Verifier Test Matrix).

13.3.10. Relying Party Provider Backend Federation Endpoint¶

The Relying Party MUST provide its Entity Configuration through the /.well-known/openid-federation endpoint, according to Section trust:Entity Configuration. Technical details are provided in Section Relying Party Entity Configuration.

13.3.11. Relying Party Provider Backend Nonce Endpoint¶

The Relying Party Nonce Endpoint allows the Verifier App to request a cryptographic nonce from the Relying Party Provider Backend. The nonce serves as an unpredictable, single-use challenge to ensure freshness and prevent replay attacks.

Further details on the Nonce Request and Response are provided in the Mobile Application Nonce Request and Mobile Application Nonce Request Sections, respectively.

13.3.12. Relying Party Verifier App Initialization Endpoint¶

The Verifier App Initialization Endpoint allows for the initialization of Verifier Apps, consisting in the registration of a pair of long-lived, securely stored Cryptographic Hardware Keys.

Further details on the Verifier App Initialization Request and Response are provided in the Mobile Application Instance Initialization Request and Mobile Application Instance Initialization Response Sections, respectively.

13.3.13. Relying Party Provider Backend Key Binding Endpoint¶

The Relying Party Key Binding Endpoint enables Verifier Apps to bind the newly created pair of keys, which will be associated with an Access Certificate, to the Verifier App, by relying on a proof of possession of the Cryptographic Hardware Keys generated during the Mobile Application Instance Initialization phase. Before completing the process, the Relying Party Provider Backend also needs to verify the integrity of the Verifier App.

13.3.13.1. Relying Party Provider Backend Key Binding Request¶

Further details on the Relying Party Key Binding Request are provided in the Mobile Application Key Binding Request section.

The typ header of the Integrity Request JWT assumes the value rp-kb+jwt.

13.3.13.2. Relying Party Provider Backend Key Binding Response¶

Upon a successful request, the Relying Party Provider Backend provides an HTTP Response with a 204 No Content status code.

Below is a non-normative example of a Key Binding Request Response.

HTTP/1.1 204 No content

If any errors occur during the process, an error response is returned. Further details on the error response are provided in the Mobile Application Key Binding Error Response section.

13.3.14. Relying Party Provider Backend Access Certificate Endpoint¶

The Relying Party Access Certificate Endpoint enables Verifier Apps to obtain an Access Certificate.

13.3.14.1. Relying Party Provider Backend Access Certificate Request¶

The Access Certificate Request uses the HTTP POST method with Content-Type set to application/json.

The request includes the following body parameter:

Parameter	Description	Reference
csr	The CSR generated by the Verifier App, encoded in the `base64url` format as defined in RFC 2511.

Below is a non-normative example of an Access Certificate Request.

POST /access-certificate HTTP/1.1
Host: relying-party.example.org
Content-Type: application/json

{
  "csr": "MIIBvzCCAa..."
}

13.3.14.2. Relying Party Provider Backend Access Certificate Response¶

Upon a successful request, the Relying Party Access Certificate Endpoint provides an HTTP Response with a 200 OK status code and the Access Certificate. The Access Certificate Response, which uses application/json as the Content-Type, includes the following body parameters:

Parameter	Description	Reference
access_certificate	The Access Certificate generated by the CSR.	This specification.

Below is a non-normative example of an Access Certificate Response.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_certificate": "hajdnhaghSDGns..."
}

If any errors occur, the Relying Party Access Certificate Endpoint returns an error response. The response uses application/json as the content type and includes the following parameters:

error. The error code.

error_description. Text in human-readable form providing further details to clarify the nature of the error encountered.

Below is a non-normative example of an Access Certificate Error Response.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "error": "invalid_request",
    "error_description": "The public key in the CSR is different from the one associated with the Cryptographic Hardware Keys."
}

The following table lists HTTP Status Codes and related error codes that MUST be supported for the error response, unless otherwise specified:

HTTP Status Code	Error Code	Description
`400 Bad Request`	`bad_request`	The request is malformed, missing required parameters (e.g., header parameters or integrity assertion), or includes invalid and unknown parameters.
`403 Forbidden`	`invalid_request`	The public key in the CSR does not match the public key associated with the Cryptographic Hardware Keys.
`500 Internal Server Error`	`server_error`	The request cannot be fulfilled because the Endpoint encountered an internal problem.
`503 Service Unavailable`	`temporarily_unavailable`	The request cannot be fulfilled because the Endpoint is temporarily unavailable (e.g., due to maintenance or overload).

13.3.15. Relying Party Erasure Endpoint¶

The Erasure Endpoint allows Wallet Instances to request deletion of attributes presented to the Relying Party, supporting user privacy rights and regulatory compliance.

For detailed implementation requirements, see Relying Party Erasure Endpoint.