Overview
The authorization endpoint serves as the entry point for the OAuth 2.0 authorization process. It provides the correct redirect to the concrete authorization method based on the configured client type.
When a request_uri provides access to a request object, all mandatory parameters can also be provided as part of that object.
Endpoint
GET /api/v1/authorization
Query Parameters
Session state identifier used to maintain state between the request and callback.Example: 274e7465-cc9d-4cad-b75f-190db927e56a
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
The URI to redirect to after authorization is complete.Example: https://my-app.com/redirect
URI pointing to a JWT request object containing the authorization request parameters.Example: https://my-app.com/request.jwt
The scope of the access request. Defines what credentials or permissions are being requested.Example: openid
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
The type of response expected. Currently only code is supported.Enum: code
Response
302 - Redirect
A redirect to the appropriate authorization entry point based on the client configuration:
- DEEPLINK: Redirects to a same-device flow using an OID4VP deeplink
- FRONTEND_V2: Redirects to the V2 login QR page at
/api/v2/loginQR
The redirect URL in the response header, pointing to the next step in the authorization flow.
400 - Bad Request
Detailed error description.
Examples
curl -X GET "https://verifier.example.com/api/v1/authorization?state=274e7465-cc9d-4cad-b75f-190db927e56a&client_id=packet-delivery-portal&redirect_uri=https://my-app.com/redirect&scope=openid&nonce=BfEte4DFdlmdO7a_fBiXTw&response_type=code" \
-L
Common Errors
Missing Required Parameters: Ensure all required parameters (state, nonce) are provided. Missing parameters will result in a 400 Bad Request error.
| Error Code | Summary | Details |
|---|
| 400 | no_state_provided | Authentication requires a state provided as query parameter. |
| 400 | no_client_id_provided | Authentication requires a client-id provided as a parameter. |
| 400 | no_scope_provided | Authentication requires a scope provided as a parameter. |
| 400 | no_nonce_provided | Authentication requires a nonce provided as a query parameter. |
| 400 | invalid_response_type | Authentication requires the response_type to be code. |
| 500 | unresolvable_request_object | Was not able to get the request object from the client. |
| 500 | invalid_audience | Audience of the request object was invalid. |
Implementation Notes
-
The endpoint supports two authorization types configured per client:
- DEEPLINK: Initiates a same-device flow with OID4VP protocol
- FRONTEND_V2: Redirects to the QR code presentation page
-
When using
request_uri, the endpoint will fetch the JWT request object and extract parameters from it. The request object’s audience must include the verifier’s host.
-
The protocol (http/https) is automatically detected from the incoming request.