# Credential issuance (DCP)

{% 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 `/credentials` endpoint with a `CredentialRequestMessage` requests the issuance of a credential.

{% hint style="info" %}
The `POST` request to the `/credentials` is an **OPTIONAL** endpoint and is part of the iSHARE Framework's Verifiable Credentials support in line with the **Decentralised Claims Protocol (DCP)**.
{% endhint %}

## Request issuance or storage of a Verifiable Credential

> If invoked with a credential-request message, requests the issuance of a Verifiable Credential according to the Eclipse Decentralized Claims Protocol v1.0 specification. This is applicable to issuers only.\
> If invoked with a credential-message, requests the storage of a credential, applicable to all roles (participants), since all roles must be able to store credentials.\
> More information in the  \[DCP specification of the credential request API]\(<https://eclipse-dataspace-dcp.github.io/decentralized-claims-protocol/v1.0/#credential-request-api>) and the \[DCP specification of the storage API]\(<https://eclipse-dataspace-dcp.github.io/decentralized-claims-protocol/v1.0/#storage-api>).

```json
{"openapi":"3.1.0","info":{"title":"iSHARE Decentralized Claims Protocol (DCP) API specifications","version":"3.0"},"tags":[{"name":"Issuer","description":"Endpoints relevant for the VC Issuer role (e.g., issuing credentials, issuer metadata)."},{"name":"Holder","description":"Endpoints relevant for the VC Holder role (e.g., storing credentials, receiving offers)."}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"iSHARE JWT Bearer token authentication"}}},"paths":{"/credentials":{"post":{"tags":["Issuer","Holder"],"summary":"Request issuance or storage of a Verifiable Credential","description":"If invoked with a credential-request message, requests the issuance of a Verifiable Credential according to the Eclipse Decentralized Claims Protocol v1.0 specification. This is applicable to issuers only.\nIf invoked with a credential-message, requests the storage of a credential, applicable to all roles (participants), since all roles must be able to store credentials.\nMore information in the  [DCP specification of the credential request API](https://eclipse-dataspace-dcp.github.io/decentralized-claims-protocol/v1.0/#credential-request-api) and the [DCP specification of the storage API](https://eclipse-dataspace-dcp.github.io/decentralized-claims-protocol/v1.0/#storage-api).","operationId":"issue-credential","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/x-ext/1d11beb"},{"$ref":"#/x-ext/30ea372"}]}}}},"responses":{"201":{"description":"Credential (request) created successfully","headers":{"Location":{"description":"URL to the credential request status endpoint (only after credential issuance request)","schema":{"type":"string","format":"uri"}}}},"400":{"description":"Bad Request - Invalid request"},"401":{"description":"Unauthorized - Invalid or missing authentication"},"403":{"description":"Forbidden - Insufficient permissions to issue credential"},"500":{"description":"Internal Server Error"}}}}}}
```

### Request model

The model for the CredentialRequestMessage is defined in: <https://eclipse-dataspace-dcp.github.io/decentralized-claims-protocol/v1.0/resources/issuance/credential-request-message-schema.json>.

* `@context`\
  **Array of Strings**. Root level. <mark style="color:red;">(Required)</mark>\
  Specifies a valid Json-Ld context. Must contain `"https://w3id.org/dspace-dcp/v1.0/dcp.jsonld"`
* `type`\
  **String**. Root level. <mark style="color:red;">(Required)</mark>\
  A string specifying the CredentialRequestMessage type. Must contain `"CredentialRequestMessage"`
* `holderPid`\
  **String**. Root level. <mark style="color:red;">(Required)</mark>\
  A string corresponding to the request id on the Holder side.
* `credentials`\
  **Array of objects**. Root level. <mark style="color:red;">(Required)</mark>\
  An array of objects with an id property, each referencing a CredentialObject.
  * `id`\
    **String**. Contained in credential object. <mark style="color:red;">(Required)</mark>\
    ID referencing an id value of an object in the credentialsSupported returned from the Issuer Metadata endpoint.

### Example request

```json
POST /credentials HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json

{
  "@context": [
    "https://w3id.org/dspace-dcp/v1.0/dcp.jsonld"
  ],
  "type": "CredentialRequestMessage",
  "holderPid": "holderPid",
  "credentials": [
    {
      "id": "d5c77b0e-7f4e-4fd5-8c5f-28b5fc3f96d1"
    },
    {
      "id": "c0f81e68-6d35-4f9d-bc04-51e511b2e46c"
    }
  ]
}
```

### Response model

After success, a 201 response will be provided. The response contains a header "Location" that contains a URL pointing to the status of the request. This URL or the ID in the URL must be stored by the issuance requestor to request the [status of credential issuance](https://dev.ishare.eu/all-roles-common-endpoints/m2m-verifiable-credential-endpoints/credential-status-dcp) in a later stage.