# Credential storage (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 `CredentialMessage` requests the storage of a credential. All roles (participants) must support this endpoint, since all roles must be able to store credentials. The endpoint would typically be provided by a Wallet provider.

{% 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 CredentialMessage is defined in: <https://eclipse-dataspace-dcp.github.io/decentralized-claims-protocol/v1.0/resources/issuance/credential-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 `"CredentialMessage"`
* `credentials`\
  **Array of objects**. Root level.\
  An array of Credential Container objects.
  * `credentialType`\
    **String**. Contained in Credential Container object. <mark style="color:red;">(Required)</mark>\
    A single string specifying type of credential. Could contain a reference to a credential type defined in the iSHARE Framework (as Credential Schema).
  * `payload`\
    **String**. Contained in Credential Container object. <mark style="color:red;">(Required)</mark>\
    A [Json Literal](https://www.w3.org/TR/json-ld11/#json-literals) containing a Verifiable Credential defined by VC DataModel version of the selected profile.
  * `format`\
    **String**. Contained in Credential Container object. <mark style="color:red;">(Required)</mark>\
    A JSON string that describes the format of the credential to be issued. Typically contains `"jwt"`.
* `issuerPid`\
  **String**. Root level. <mark style="color:red;">(Required)</mark>\
  A string corresponding to the issuance id on the Issuer side.
* `holderPid`\
  **String**. Root level.\
  A string corresponding to the request id on the Holder side.
* `status`\
  **String**. Root level. <mark style="color:red;">(Required)</mark>\
  A string stating whether the request was successful (`ISSUED`) or rejected (`REJECTED`).

### 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": "CredentialMessage",
  "credentials": [
    {
      "credentialType": "FrameworkCompliance",
      "payload": "",
      "format": "jwt"
    },
    {
      "credentialType": "DataspaceMembership",
      "payload": "",
      "format": "jwt"
    }
  ],
  "issuerPid": "issuerPid",
  "holderPid": "holderPid",
  "status": "ISSUED"
}
```

### Response model

After success, a 201 response will be provided.