Use Access Grants to Access Resources#

This page details how an agent can use Inrupt’s solid-client-access-grants library to use approved Access Grants to access Pod Resource(s).

Access Requests and Grants

The following Inrupt products are available to support Access Requests and Grants:

  • solid-client-access-grants library for managing access requests and grants

  • Inrupt’s Enterprise Solid Server (ESS) provides support for access requests and grants. ESS serializes the access requests and grants as Verifiable Credentials (VCs).

  • Inrupt’s PodBrowser supports access request management.

Retrieve Access Grants#

As part of the Access Request/Grant flow, when the Resource Owner grants or denies the Access Request, the id of the approved/denied Access Grant (serialized as VC) is sent back to the requesting app as a query parameter.

The requesting app can use getAccessGrantFromRedirectUrl to get the Access Grant (serialized as VC)

import {
   getAccessGrantFromRedirectUrl
} from "@inrupt/solid-client-access-grants";

// ...

const myAccessGrantVC = await getAccessGrantFromRedirectUrl(
   myURL,
   { fetch: fetch }             // fetch from authenticated Session
);

Read and Write SolidDataset#

If the requestor has an access grant (serialized as VC) that allows the requestor to read a SolidDataset, the requestor can retrieve that SolidDataset using the @inrupt/solid-client-access-grants function getSolidDataset.

If the requestor has an access grant VC that allows the requestor to write or append a SolidDataset, the requestor can save that SolidDataset using the @inrupt/solid-client-access-grants function saveSolidDatasetAt

To read or modify the data in the SolidDataset, use the @inrupt/solid-client library’s functions.

Disambiguation

Ensure that you are using getSolidDataset and saveSolidDatasetAt from the @inrupt/solid-client-access-grants and not the @inrupt/solid-client library.

import {
   getSolidDataset,
   saveSolidDatasetAt
} from "@inrupt/solid-client-access-grants";

import {
  getThing,
  getStringNoLocale,
  addUrl,
  addStringNoLocale,
  buildThing,
  createThing,
  setThing
} from "@inrupt/solid-client";

// ...


// Use `getSolidDataset` from `@inrupt/solid-client-access-grants`
const mySolidDataset = await getSolidDataset(
   resourceURL,
   myAccessGrantVC,  // Access Grant (serialized as VC) that provides the user read access to get the SolidDataset
   { fetch : fetch } // From the requestor's (i.e., ExamplePrinter's) authenticated session
)

// Use functions from `@inrupt/solid-client` to modify the SolidDataset
// const myDataThing = getThing( ... );
// ...
// let myUpdatedSolidDataset = ...;
// ...

// Use `saveSolidDatasetAt` from `@inrupt/solid-client-access-grants`
const savedSolidDataset = await saveSolidDatasetAt(
  resourceURL,
  myUpdatedSolidDataset,
  myAccessGrantVC,             // Access Grant (serialized as VC) that grants the user write access to save the SolidDataset
  { fetch: fetch }             // fetch from authenticated Session
);

To access the contents of a SolidDataset, use the @inrupt/solid-client library’s functions. For examples, see:

Read Other Files (Non-RDF Resources)#

If the requestor has an Access Grant (serialized as VC) that allows the requestor to read a file (e.g., .pdf, .jpeg, etc.), the requestor can retrieve the file using the @inrupt/solid-client-access-grants function getFile.

Disambiguation

Ensure that you are using getFile from the @inrupt/solid-client-access-grants and not the @inrupt/solid-client library.

import {
   getFile
} from "@inrupt/solid-client-access-grants";

// ...

// file is a Blob (see https://developer.mozilla.org/docs/Web/API/Blob)
 const file = await getFile(
   fileURL,               // File in Pod to Read
   myAccessGrantVC,       // Access Grant (serialized as VC) that grants the user read access to the File
   { fetch: fetch }       // fetch from authenticated session
 );