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.