# Authorization Endpoint (OpenID4VP)

{% hint style="info" %}
Specifications and best practice implementations for Verifiable Credentials are currently being developed. This page is expected to be updated, closely following these developments.
{% endhint %}

The `GET` or `POST` request to the authorisation endpoint initiates a verifiable presentation request. This endpoint is part of the OpenID for Verifiable Presentations (OpenID4VP) protocol and follows OAuth 2.0 authorisation flow patterns.

{% hint style="info" %}
The authorisation endpoint for OpenID4VP is an **OPTIONAL** endpoint and is part of the iSHARE Framework's Verifiable Credentials support in line with **OpenID for Verifiable Presentations (OpenID4VP)**.
{% endhint %}

### Endpoint

```
GET /authorize
POST /authorize
```

The URL for this endpoint is provided in the Verifier Metadata (see [Verifier Metadata](https://dev.ishare.eu/all-roles-common-endpoints/openid4vp-endpoints/verifier-metadata-openid4vp)). This endpoint may be the same as the standard iSHARE authorisation endpoint, but supports additional parameters for verifiable presentation requests.

### Request model

#### Parameters

The request parameters follow the OAuth 2.0 authorisation request format with OpenID4VP-specific additions:

* `response_type`\
  **String**. <mark style="color:red;">(Required)</mark>\
  OAuth 2.0 response type. For OpenID4VP, MUST include `vp_token` (e.g., `vp_token` or `code vp_token`).
* `client_id`\
  **String**. <mark style="color:red;">(Required)</mark>\
  The client identifier. Within iSHARE, this MUST contain a valid [Party Identifier](https://framework.ishare.eu/detailed-descriptions/functional/functional-requirements-per-role/party-identification) when applicable.
* `redirect_uri`\
  **String**. <mark style="color:red;">(Required)</mark>\
  The redirect URI where the response will be sent.
* `scope`\
  **String**.\
  OAuth 2.0 scope parameter. May include credential types or presentation scopes.
* `presentation_definition`\
  **Object**.\
  A [Presentation Definition](https://identity.foundation/presentation-exchange/spec/v2.1.1/#presentation-definition) object specifying the required credentials and constraints.
* `presentation_definition_uri`\
  **String**.\
  A URI pointing to a Presentation Definition document.
* `nonce`\
  **String**.\
  A nonce to prevent replay attacks.
* `state`\
  **String**.\
  OAuth 2.0 state parameter for maintaining state between request and callback.

### Example request

```
GET /authorize?response_type=vp_token&client_id=did:ishare:EU.NL.NTRLNL-10000001&redirect_uri=https://wallet.example.com/cb&scope=openid&presentation_definition_uri=https://verifier.ishare.eu/presentation-definitions/participant-credential&nonce=abc123&state=xyz789
Host: verifier.ishare.eu
```

### Response model

The response follows OAuth 2.0 authorization response format:

* `vp_token`\
  **String**.\
  A verifiable presentation token (when `response_type` includes `vp_token`).
* `code`\
  **String**.\
  An authorization code (when `response_type` includes `code`).
* `state`\
  **String**.\
  The state parameter value from the request.
* `presentation_submission`\
  **Object**.\
  A [Presentation Submission](https://identity.foundation/presentation-exchange/spec/v2.1.1/#presentation-submission) object when using presentation definitions.

### Example response

The response is typically a redirect to the `redirect_uri` with parameters:

```
https://wallet.example.com/cb?vp_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...&state=xyz789
```

### iSHARE-Specific Requirements

Within iSHARE, the following requirements apply:

* Clients (holder applications) MUST NOT be pre-registered. A look-up in the Participant Registry is sufficient.
* The `client_id` MUST contain a valid Party Identifier when applicable.
* The verifier MUST validate the requesting party's authorization to request verifiable presentations.
* The authorization endpoint may be the same as the standard iSHARE authorization endpoint used for OpenID Connect flows, but MUST support the additional OpenID4VP parameters.