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”.