Access Prompt 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 initiating and validating Access Request flows with third-party applications:

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

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

Access Request Prompt

The Wallet Service provides an endpoint that sends a prompt to a third party, initiating an Access Request flow.

The request from the Wallet Service to the third party will use an operator-configured API key for authentication. The payload of that request will include the WebID from the current user’s session and use it to identify the inbox to which it should send the Access Request.

Method	POST
Content-Type	application/json
Endpoint	https://datawallet.{ESS Domain}/accessprompt
Payload	A JSON object representing the third-party application and the requested resource type.

Input

The body of the request contains a JSON object with the unique identifier of the third-party application and the URI of the resource to which it should request access.

Body	Value
Content-Type	application/json
resource	The URI of the resource to which the third-party application should request access.
client	An unique identifier representing the third-party application which was pre-registered with the Wallet Service.

Example request

{
  "resource": "https://storage.example/data/MyResource",
  "client": "cbefb903-d921-423f-9f44-4119cdd749d3"
}

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

Access Request Validation

The Wallet Service provides an endpoint that validates an access request and searches the Wallet for data of the requested type.

Method	GET
Content-Type	application/json
Endpoint	https://datawallet.{ESS Domain}/accessprompt/resource
Payload	A JSON object representing the third-party application and the requested resource type.

Input

The body of the request contains a JSON object with the WebID of the third-party application and the requested resource type.

Body	Value
Content-Type	application/json
webId	The WebID of the third-party application requesting access to a resource.
type	The type of resource (or credential) the third-party application would like to access.

Example request

{
  "webId": "https://id.example/agent",
  "type": "CredentialType"
}

Output

Example response

{
  "webId": "https://id.example/agent",
  "resource": "https://storage.example/data/MyCredential",
  "resourceName": "MyCredential",
  "logo": "https://images.example/logo.png",
  "ownerName": "Example Name"
}

The fields have the following values:

Field	Value
webId	The WebID of the third-party application requesting access to a resource.
resource	The URI of the first resource within the Wallet which matches the requested type.
resourceName	The short-name of the first resource within the Wallet which matches the requested type, without the hostname and parent path.
logo	A URL referencing a logo, if available, for display in a user interface.
ownerName	The name of the party requesting access to a resource, if available.