←Back to OID4VP Documentation
Skip to main content
API docs by Redocly

Universal OID4VP (0.1.0)

Download OpenAPI specification:Download

URL: https://github.com/FIDEScommunity/universal-oid4vp License: Apache2

This universal API enables standardized integration with OID4VP-capable Relying Party agents. It minimizes custom integration efforts by defining a baseline for software interoperability. Due to privacy concerns, it favors POST methods with payloads instead of query/path parameters to reduce log-leakage of sensitive values like query IDs or correlation identifiers.

Backend

The Backend integration endpoints

Create authorization request and session

Creates a new OID4VP Authorization Request that can be used to request Digital Credentials from a wallet. Returns URIs needed to initiate the auth flow and check its status. The queryId passed in needs to be known to the agent. This endpoint is protected using OAuth2/OIDC normally with a confidential client. Do not call from the frontend!

Authorizations:
oAuth2bearerAuth
Request Body schema: application/json

Configuration for the authorization request

correlation_id
string

Optional Id typically containing a business key that can be used to later query the status. If not provided a random UUID will be assigned to the correlationId and will be returned in the response.

query_id
required
string

Identifier for the query (DCQL or PE)

request_uri_base
string
Default: "oid4vp://"

The base URI to be used for request URIs. Defaults to "oidp4vp://". It is mainly useful for web/organizational wallets that have an https:// URI for OID4VP

request_uri_method
string (RequestUriMethod)
Default: "get"
Enum: "get" "post"

Determines whether the request_uri should be access by a GET or by a POST by the wallet

client_id
string

The client id and schema as defined in RFC6749 (client_id) and OID4VP (scheme)

response_type
string (ResponseType)
Default: "vp_token"
Enum: "vp_token" "id_token"

The OID4VP response type to use. FIXME Needs to be changed since response_type is a whitespace delimited strung and thus enums are not the correct approach

response_mode
string (ResponseMode)
Default: "direct_post"
Enum: "direct_post" "direct_post.jwt"

Whether to use regular authorization responses or encrypted (direct_post.jwt) authorization responses

transaction_data
Array of strings

Array of strings, where each string is a base64url encoded JSON object that contains a typed parameter set with details about the transaction that the Verifier is requesting the End-User to authorize.

object (QRCodeOpts)

As soon as you include this object the OID4VP agent has to generate a QR code. Every RP implementation needs to support this, as we want to make it easy on the integration side. The integration side can choose whether they create their own QR codes, or whether they want to use the QR code from the RP. Thus every RP conforming to this spec should support generating a QR code in data-uri format. No property is mandatory, so a "qrCodeOpts": {} is already valid and generates a QR with the default properties applied. A RP implementation is free to implement additional properties like logo's etc. This API only mandates a few common properties to not make it too complex for RPs. If the integrating app wants to use their own QR codes they simply need to omit the qr_code param from the request. The agent should not generate a QT code in this case

direct_post_response_redirect_uri
string

Optional URI where the user agent on the wallet device should redirect when completing the interaction succesfully

object (CallbackOpts)

Responses

Callbacks

Request samples

Content type
application/json
Example
{
  • "correlation_id": "my-business-key-or-uuid",
  • "query_id": "example-dcql-id",
  • "client_id": "redirect_uri%3Ahttps%3A%2F%2Fexample.com%2Fcb"
}

Response samples

Content type
application/json
{
  • "correlation_id": "2cc29d1c-7d00-46f8-b0ae-b4779d2ff143",
  • "query_id": "example-dcql-id",
  • "request_uri": "openid-vc://?request_uri=https://example.com/siop/definitions/ExampleSdJwtId/auth-requests/b5cab09e-7c08-42c9-870b-c2b83a2c8acd",
  • "status_uri": "https://example.com/oid4vp/backend/auth/status",
  • "qr_uri": "data:image/png;base64,iVBORw0<snip>ef="
}

Callback payload samples

Callback
POST: Authorization status callback
Content type
application/json
{
  • "status": "authorization_request_created",
  • "correlation_id": "2cc29d1c-7d00-46f8-b0ae-b4779d2ff143",
  • "error": {
    },
  • "query_id": "ExampleSdJwtId",
  • "last_updated": 1706515200000,
  • "verified_data": {
    }
}

Get authorization session status

Checks the current status of an Authorization Request session. Can optionally include verified credential data in the response when the status is 'verified'.

Authorizations:
oAuth2bearerAuth
path Parameters
correlation_id
required
string

The correlation_id as returned from the CreateAuthorizationRequestResponse

Responses

Response samples

Content type
application/json
{
  • "status": "authorization_request_created",
  • "correlation_id": "2cc29d1c-7d00-46f8-b0ae-b4779d2ff143",
  • "error": {
    },
  • "query_id": "ExampleSdJwtId",
  • "last_updated": 1706515200000,
  • "verified_data": {
    }
}

Remove authorization request state

Deletes all state associated with an authorization request. Use for cleanup after completion or timeout.

Authorizations:
oAuth2bearerAuth
path Parameters
correlation_id
required
string

The correlation_id as returned from the CreateAuthorizationRequestResponse

Responses

Response samples

Content type
application/json
{
  • "status": 500,
  • "message": "Could not verify auth status",
  • "error_details": "string"
}