Skip to main content

​
Overview

The VCVerifier provides two versions of QR code presentation endpoints for initiating the SIOP (Self-Issued OpenID Provider) authentication flow. These endpoints return rendered HTML pages containing QR codes that users can scan with their credential wallets.
Version 2 (/api/v2/loginQR) includes additional features like WebSocket support for real-time updates and QR code expiration handling.

​
Endpoint

GET /api/v2/loginQR

​
Description

Returns a rendered HTML page with a QR code that encodes the login starting point for the SIOP flow. The QR code contains an OpenID URL like: 
openid://?scope=something&response_type=rt&response_mode=rm&client_id=ci&redirect_uri=uri&state=state&nonce=nonce&request_mode=urlEncoded

​
Query Parameters

​
state
string
required
Session state identifier used to maintain state between the request and callback.Example: 274e7465-cc9d-4cad-b75f-190db927e56a
​
client_id
string
The identifier of the client/service that intends to start the authentication flow. Used to retrieve the scope and trust services for verification.Example: packet-delivery-portal
​
redirect_uri
string
The URI to redirect to after authorization is complete.Example: https://my-app.com/redirect
​
request_uri
string
URI pointing to a JWT request object containing the authorization request parameters. When provided, parameters are extracted from the request object.Example: https://my-app.com/request.jwt
​
scope
string
The scope of the access request. Defines what credentials or permissions are being requested.Example: openid
​
nonce
string
required
A unique string value used to associate a client session with an ID Token and to mitigate replay attacks.Example: 274e7465-cc9d-4cad-b75f-190db927e56a
​
request_mode
string
default:"byReference"
Mode to be used for the authorization request.Enum: urlEncoded | byValue | byReferenceDefault: byReference

​
Response

​
200 - Success

Returns a rendered HTML page containing:
  • The QR code for scanning
  • WebSocket URL for real-time updates
  • QR code expiration timestamp
  • Authentication request details
​
Content-Type
string
text/html

​
400 - Bad Request

Returned when required parameters are missing or invalid.
​
summary
string
Error summary message.
​
details
string
Detailed error description.

​
Examples

curl -X GET "https://verifier.example.com/api/v2/loginQR?state=274e7465-cc9d-4cad-b75f-190db927e56a&client_id=packet-delivery-portal&redirect_uri=https://my-app.com/redirect&scope=openid&nonce=BfEte4DFdlmdO7a_fBiXTw" \
  -H "Accept: text/html"

​
V1 Login QR (Legacy)

​
Endpoint

GET /api/v1/loginQR

​
Description

Legacy version of the QR code presentation endpoint. Returns a simpler HTML page with a QR code for the SIOP flow.
This is the V1 endpoint. Consider using /api/v2/loginQR for enhanced features including WebSocket support and better error handling.

​
Query Parameters

​
state
string
required
Session state identifier.Example: 274e7465-cc9d-4cad-b75f-190db927e56a
​
client_callback
string
required
Endpoint of the client to receive the JWT.Example: https://my-portal.com/auth_callback
​
client_id
string
The identifier of the client/service initiating the authentication flow.Example: packet-delivery-portal
​
nonce
string
Unique string value for session association and replay attack mitigation.Example: 274e7465-cc9d-4cad-b75f-190db927e56a
​
request_mode
string
default:"byReference"
Mode to be used for the authorization request.Enum: urlEncoded | byValue | byReferenceDefault: byReference

​
Response

​
200 - Success

Returns a rendered HTML page containing the QR code.
​
Content-Type
string
text/html

​
400 - Bad Request

​
summary
string
Error summary message.
​
details
string
Detailed error description.

​
Examples

curl -X GET "https://verifier.example.com/api/v1/loginQR?state=274e7465-cc9d-4cad-b75f-190db927e56a&client_callback=https://my-portal.com/auth_callback&client_id=packet-delivery-portal&nonce=BfEte4DFdlmdO7a_fBiXTw" \
  -H "Accept: text/html"

​
Common Errors

Error CodeSummaryDetails
400no_state_providedAuthentication requires a state provided as query parameter.
400NoCallbackProvidedA callback address has to be provided as query-parameter. (V1 only)
400no_redirect_uri_providedToken requests require a redirect_uri. (V2 when no request_uri)
400no_nonce_providedAuthentication requires a nonce provided as a query parameter. (V2 only)
500qr_generation_errorAn error occurred while generating the QR code.
500unresolvable_request_objectWas not able to get the request object from the client.
500invalid_audienceAudience of the request object was invalid.

​
Implementation Notes

​
Request URI Support (V2)

When using the request_uri parameter:
  1. The endpoint fetches the JWT request object from the provided URI
  2. Parameters are extracted from the request object
  3. The audience (aud) in the request object must include the verifier’s host
  4. Extracted parameters override query parameters

​
Request Modes

  • byReference (default): The request is passed by reference via a URI
  • byValue: The complete request object is included in the QR code
  • urlEncoded: Parameters are URL-encoded in the QR code

​
WebSocket Support (V2)

The V2 endpoint provides a WebSocket URL in the format: 
wss://verifier.example.com/ws?state={state}
This enables real-time updates on the authentication status.

Build docs developers (and LLMs) love

Get started for freeTalk to us