Inbox Endpoint#

Added in version 2.3.

Developer Preview

The ESS Wallet Service endpoints are available as part of a Developer Preview program to allow early access to these features. Please be aware that these APIs may change.

The ESS Wallet Service provides the following endpoint for interacting with resources stored in the Wallet inbox:

https://datawallet.{ESS Domain}/inbox

Note

To access the /inbox endpoint, users must be authenticated. The endpoint supports the use of HTTP-only, secure session cookies.

List Inbox Items#

The Wallet Service provides an endpoint to list all of the items currently stored in the inbox of the Wallet.

Method	`GET`
Content-Type	`application/json`
Endpoint	`https://datawallet.{ESS Domain}/inbox`
Payload	none

Output#

Returns an array of inbox items.

Example response

[
  {
    "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "identifier": "https://example.com/",
    "webId": "https://id.{DOMAIN}/{username}",
    "resource": "https://storage.example/data/MyResource",
    "resourceName": "MyResource",
    "forPurpose": "https://example.com/",
    "expirationDate": "2024-07-19T09:18:52.233Z",
    "issuedDate": "2024-07-19T09:18:52.233Z",
    "modes": [
      "read"
    ],
    "logo": "https://images.example/logo.png",
    "ownerName": "Example Name",
    "isRDFResource": true
  }
]

The fields have the following values:

Field	Value
`uuid`	A unique identifier of this inbox item.
`identifier`	The URI identifying the inbox item.
`webId`	The WebID of the party requesting access to a resource.
`resource`	The URI of the resource within the Wallet to which access has been requested.
`resourceName`	The short-name of the resource within the Wallet to which access has been requested, without the hostname and parent path.
`forPurpose`	The URI of the document describing the purpose of this Access Request.
`expirationDate`	The expiration date of the Access Request in ISO-8601 format.
`issuedDate`	The date of issuance of the Access Request in ISO-8601 format.
`modes`	The modes of access that will be granted if this access request is approved (e.g. `read`, `write`, `append`).
`logo`	A URI identifying a logo to associate with the party requesting access to a resource (for display within the Wallet user interface).
`ownerName`	The name of the party requesting access to a resource, if available.
`webId`	The WebID of the party requesting access to a resource.
`isRDFResource`	Boolean value indicating whether this resource contains RDF data.

Read Inbox Item#

The Wallet Service provides an endpoint to get the content of an inbox item.

Method	`GET`
Content-Type	`/`
Endpoint	`https://datawallet.{ESS Domain}/inbox/{uuid}`
Payload	none

Input#

Path Parameter	Value
`uuid`	The UUID of the inbox item to read.

Output#

The content of the inbox item.

Delete Inbox Item#

The Wallet Service provides an endpoint to delete an inbox item.

Method	`DELETE`
Content-Type	`application/json`
Endpoint	`https://datawallet.{ESS Domain}/inbox/{identifier}`
Payload	none

Input#

Path Parameter	Value
`uuid`	The UUID of the inbox item to be deleted.

Output#

Upon completion, a status message is returned.

Example response

{
    "message": "success"
}

The fields have the following values:

Field	Value
`message`	A successful operation includes the string “success”.
`error`	An unsuccessful operation describes the failure category, such as “UNAUTHORIZED”.

Verify Access Request#

The Wallet Service provides an endpoint to verify that an Access Request within the inbox is valid and passes the verification checks described by the Access Grant Service.

Method	`GET`
Content-Type	`application/json`
Endpoint	`https://datawallet.{ESS Domain}/inbox/{uuid}/verify`
Payload	none

Input#

Path Parameter	Value
`uuid`	The UUID of the inbox item to be verified.

Output#

Upon completion, the verification results are returned.

Example Response

{
  "identifier": "https://credential.example/{uuid}",
  "detail": {
    "checks": [
      "string"
    ],
    "warnings": [
      "string"
    ],
    "errors": [
      "string"
    ]
  },
  "status": "Invalid"
}

Field	Value
`checks`	Lists the checks performed during verification.
`warnings`	Lists any warnings that occurred during verification.
`errors`	Lists any errors that occurred during verification.
`status`	The status of the verification, either `Valid` or `Invalid`.

Grant Access Request#

The Wallet Service provides an endpoint to generate an Access Grant based on an inbox Access Request.

Method	`PUT`
Content-Type	`application/json`
Endpoint	`https://datawallet.{ESS Domain}/inbox/{uuid}/grantAccess`
Payload	none

Input#

Path Parameter	Value
`uuid`	The UUID of the inbox item to be used to generate an Access Grant.

Output#

Upon completion a description of the new Access Grant is returned that can be used to display the Grant within the Wallet user interface.

Example Response

{
  "uuid": "fc2f50db-bdb3-43d7-b194-9868512d2459",
  "identifier": "https://accessgrant.example/b7e42e71-8a67-44e8-b3da-fe2a778a9e28",
  "webId": "https://id.example/agent",
  "resource": "https://storage.example/data/MyResource",
  "resourceName": "MyResource",
  "forPurpose": "https://example.com/",
  "expirationDate": "2024-07-19T10:45:24.138Z",
  "issuedDate": "2024-07-19T10:45:24.138Z",
  "modes": [
    "read"
  ],
  "logo": "https://images.example/logo.png",
  "ownerName": "Example Name",
  "isRDFResource": true
}

The fields have the following values:

Field	Value
`uuid`	The unique identifier of this inbox resource.
`identifier`	An identifier of the Access Grant.
`webId`	The WebID of the party granted access to a resource.
`resource`	The URI of the resource to which access has been granted.
`resourceName`	A short name of the resource to which access has been granted.
`forPurpose`	The URI of the document describing the purpose of this Access Grant.
`expirationDate`	The expiration of the Access Grant in ISO-8601 format.
`issuedDate`	The date of issuance of the Access Grant in ISO-8601 format.
`modes`	The modes of access granted (e.g. `read`, `write`, `append`).
`logo`	A URI identifying a logo to associate with the party granted access to a resource (for display within the Wallet user interface).
`ownerName`	The name of the party granted access to a resource, if available.
`isRDFResource`	Boolean value indicating whether the resource contains RDF data.

Deny Access Request#

The Wallet Service provides an endpoint to deny an Access Request that has been added to the inbox.

Method	`PUT`
Content-Type	`application/json`
Endpoint	`https://datawallet.{ESS Domain}/inbox/{uuid}/denyAccess`
Payload	none

Input#

Path Parameter	Value
`uuid`	The UUID of the inbox item to be used to generate an Access Denial.

Output#

Upon completion, a status message is returned.

Example response

{
    "message": "success"
}

The fields have the following values:

Field	Value
`message`	A successful operation includes the string “success”.
`error`	An unsuccessful operation describes the failure category, such as “UNAUTHORIZED”.