# Credential Endpoint (OpenID4VCI)

{% 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 `POST` request to the `/credential` endpoint is where credential requests are made and verifiable credentials are issued. This endpoint is part of the OpenID for Verifiable Credential Issuance (OpenID4VCI) protocol.

{% hint style="info" %}
The `POST` request to the `/credential` is an **OPTIONAL** endpoint and is part of iSHARE Framework's Verifiable Credentials support in line with **OpenID for Verifiable Credential Issuance (OpenID4VCI)**.
{% endhint %}

### Endpoint

```
POST /credential
```

The URL for this endpoint is provided in the Credential Issuer Metadata (see [Credential Issuer Metadata](https://dev.ishare.eu/all-roles-common-endpoints/openid4vci-endpoints/credential-issuer-metadata-openid4vci)).

### Request model

#### Headers

* `Authorization`\
  **String**. <mark style="color:red;">(Required)</mark>\
  OAuth 2.0 authorization based on bearer token. MUST contain "Bearer " + access token value. The access token is obtained from the [Token Endpoint](https://dev.ishare.eu/all-roles-common-endpoints/openid4vci-endpoints/token-endpoint-openid4vci).
* `Content-Type`\
  **String**.\
  MUST be equal to `application/json`.

#### Parameters

The request body MUST be a JSON object containing:

* `format`\
  **String**.\
  The credential format requested (e.g., `vc+sd-jwt`, `mso_mdoc`). If not specified, the issuer's default format is used.
* `credential_definition`\
  **Object**.\
  The credential definition specifying the type of credential requested:
  * `type`\
    **Array of Strings**. <mark style="color:red;">(Required)</mark>\
    Array of credential types (e.g., `["VerifiableCredential", "ParticipantCredential"]`).
* `proof`\
  **Object**.\
  Proof of possession of the key material. Contains:
  * `proof_type`\
    **String**. <mark style="color:red;">(Required)</mark>\
    The proof type (e.g., `jwt`).
  * `jwt`\
    **String**.\
    The JWT proof when `proof_type` is `jwt`. This JWT MUST be signed with the holder's key and MUST include the `c_nonce` received from the token endpoint.
* `transaction_id`\
  **String**.\
  Transaction identifier for tracking the credential issuance request.

### Example request

```json
POST /credential
Host: credential-issuer.ishare.eu
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

{
  "format": "vc+sd-jwt",
  "credential_definition": {
    "type": [
      "VerifiableCredential",
      "ParticipantCredential"
    ]
  },
  "proof": {
    "proof_type": "jwt",
    "jwt": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

### Response model

The response is a JSON object containing:

* `format`\
  **String**. <mark style="color:red;">(Required)</mark>\
  The credential format of the issued credential.
* `credential`\
  **String**. <mark style="color:red;">(Required)</mark>\
  The issued verifiable credential. The format depends on the `format` value:
  * For `vc+sd-jwt`: A signed JWT containing the credential
  * For `mso_mdoc`: A mobile document format credential
* `c_nonce`\
  **String**.\
  A new nonce for subsequent credential requests.
* `c_nonce_expires_in`\
  **Integer**.\
  The lifetime in seconds of the `c_nonce`.

### Example response

```json
{
  "format": "vc+sd-jwt",
  "credential": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsInZjIjp7InR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJQYXJ0aWNpcGFudENyZWRlbnRpYWwiXX19.eyJpc3MiOiJkaWQ6aXNoYXJlOkVVLk5MLk5UUkxOTC0xMDAwMDAwMCIsInN1YiI6ImRpZDppc2hhcmU6RVUuTk4uTlRSTkwtMTAwMDAwMDEiLCJ2YyI6eyJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiUGFydGljaXBhbnRDcmVkZW50aWFsIl0sImNyZWRlbnRpYWxTdWJqZWN0Ijp7InBhcnR5SWQiOlsiZGlkOmlzaGFyZTpFVS5OTi5OVFJOTC0xMDAwMDAwMSJdLCJwYXJ0eU5hbWUiOiJUZXN0IFBhcnRpY2lwYW50In19LCJpYXQiOjE2OTk5OTk5OTksImV4cCI6MTcyMTU1NTU1NX0.signature",
  "c_nonce": "9Yz6s5t4n3",
  "c_nonce_expires_in": 300
}
```

### iSHARE-Specific Requirements

Within iSHARE, the following requirements apply:

* All issued credentials MUST conform to the [W3C Verifiable Credentials Data Model 2.0](https://www.w3.org/TR/vc-data-model-2.0/).
* Credentials MUST use schemas published at [schemas.ishare.eu](https://schemas.ishare.eu).
* Credentials MUST include a `credentialStatus` property when required by the schema (see [Bitstring Status List](https://dev.ishare.eu/introduction/getting-started/verifiable-credentials-as-part-of-the-ishare-framework#bitstring-status-list-v10)).
* The issuer MUST validate the access token and proof of possession before issuing credentials.
* The issuer MUST verify that the requesting party is authorized to receive the requested credential type.