# Use Access Grants to Access Resources ## `AccessGrantSession` The **`inrupt-client-accessgrant`** module provides an [AccessGrantSession](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/AccessGrantSession.html) that builds an authenticated [Session](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/auth/Session.html) object using both: * an OpenID-based session and * one or more access grants. Then, a [SolidClient](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/solid/SolidClient.html)/[SolidSyncClient](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/solid/SolidSyncClient.html) can use this session to access resources using the approved access grant(s). Continuing the example from [create-access-requests-grants](https://docs.inrupt.com/sdk/java-sdk/access-requests-and-grants/create-access-requests-grants "mention"), ExamplePrinter backend server, with the appropriate access grants, can access the resources for printing. For convenience, ExamplePrinter’s backend server’s code to instantiate [AccessGrantClient](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/AccessGrantClient.html) for ExamplePrinter is repeated here: ```java public class ExamplePrinterRequestingClass { private final URI PS_ACCESS_GRANT_URI = URI.create("https://vc.inrupt.com"); private Session session; // Session for ExamplePrinter. // ... Logic to initialize the ExamplePrinter's session has been omitted for brevity. private final AccessGrantClient accessgrantClient = new AccessGrantClient(PS_ACCESS_GRANT_URI) .session(session); // ... // ... } ``` #### 1. Get the Access Grant(s) to Use {% hint style="info" %} The user can only access those access grants where the user is the creator of the access grant (i.e., the grantor) or the recipient of the access grant (i.e., the grantee). That is, the ESS’ Access Grant service only returns those access grants where the user is the creator or the recipient. {% endhint %} {% tabs %} {% tab title="Fetch a Specific Access Grant" %} If the Access Grant’s id is known, the application can directly retrieve the access grant using [AccessGrantClient.fetch](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/AccessGrantClient.html#fetch\(java.net.URI,java.lang.Class\)) with the Access Grant’s id. {% hint style="info" %} The **`fetch`** operation can return expired or future access grants. {% endhint %} ```java // String grantID = "https://vc.{ESS DOMAIN}/vc/xxxxxx..."; AccessGrant accessGrant = accessgrantClient.fetch(URI.create(grantID), AccessGrant.class) .toCompletableFuture() .join(); ``` {% endtab %} {% tab title="Query for Access Grants" %} The application can use [AccessGrantClient.query](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/AccessGrantClient.html#query\(com.inrupt.client.accessgrant.AccessCredentialQuery\)) to query for active (i.e., current and not expired) access grants. To use [AccessGrantClient.query](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/AccessGrantClient.html#query\(com.inrupt.client.accessgrant.AccessCredentialQuery\)) for access grants, you can pass in a [CredentialFilter](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/CredentialFilter.html) object `CredentialFilter` that specifies the query filter values (i.e., a combination of the resource, creator, recipient, purpose, and type). You can use [CredentialFilter.Builder](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/CredentialFilter.Builder.html) and its [methods](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/CredentialFilter.Builder.html#method.summary) to build a [CredentialFilter](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/CredentialFilter.html) for access grants:
MethodDescriptions
.status

Optional. Include a credential status in the query object.

The following values are supported for access grants:

  • ACTIVE when used with AccessGrant queries, this returns all active access grants: those that have not expired and have not been revoked.
  • EXPIRED when used with AccessGrant queries, this returns all access grants that have expired.
  • REVOKED when used with AccessGrant queries, this returns all access grants that have been revoked by the resource owner.
.fromAgentOptional. Include the creator of the access grant in the query filter. This is the resource owner.
.toAgentOptional. Include the recipient of the access grant in the query filter. This is the agent that is granted access. In the example, the value is the ExamplePrinter’s WebID https://id.example.com/examplePrinter.
.resource

Optional. Include the resource in the query object.

Use this filter to return access grants bound to a specific resource.

.purpose

Optional. Include a purpose in the query object.

Use this filter to return access grants bound to a specific purpose.

.issuedWithin

Optional. Include a time constraint on the issuance date in the query object. All matched credentials will have been issued within the provided duration value.

Certain time constraints are available for use with this method, including:

.revokedWithin

Optional. Include a time constraint on the revocation date in the query object. All matched credentials will have been revoked within the provided duration value.

Certain time constraints are available for use with this method, including:

.build

Builds the CredentialFilter object.

To build a query object for access grants (i.e., CredentialFilter<AccessGrant>), specify the class AccessGrant.class to the .build method.

The following example queries for active access grants, given to ExamplePrinter, that provide access for a specific resource for the purpose of photo printing. Specifically, 1. The example uses the [CredentialFilter.Builder](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/CredentialFilter.Builder.html) and its [methods](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/CredentialFilter.Builder.html#method.summary) to: * Specify the resource `.resource(...)`, the purpose `.purpose(...)`, and the status `.status(CredentialStatus.ACTIVE)`, and * Build `.build(AccessGrant.class)` a `CredentialFilter`. 2. Calls [AccessGrantClient.query](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/AccessGrantClient.html#query\(com.inrupt.client.accessgrant.AccessCredentialQuery\)) with the built `CredentialFilter` object. ```java CredentialFilter accessGrantFilter = CredentialFilter .newBuilder() .status(CredentialFilter.CredentialStatus.ACTIVE) .resource(URI.create("https://storage.example.com/some/resource")) .purpose(URI.create("https://purpose.example.com/PhotoPrinting")) .build(AccessGrant.class); CredentialResult result = accessgrantClient .query(accessGrantFilter) .toCompletableFuture().join(); ``` 3. Navigate through the response [CredentialResult](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/CredentialResult.html) object. ```java List items = result.getItems(); if (result.nextPage().isPresent()) { CredentialResult page2 = agClientForUser .query(result.nextPage().get()) .toCompletableFuture().join(); } ``` From the list, the agent can select the access grant to use. {% endtab %} {% endtabs %} #### 2. Create an AccessGrantSession To instantiate an [AccessGrantSession](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/AccessGrantSession.html), call the constructor with the following parmeters: * OpenID-based session * Access Grants to Use For example, the following code instantiates an [AccessGrantSession](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/AccessGrantSession.html) using both the ExamplePrinter’s OpenID Session and the access grant: ```java Session agSession = AccessGrantSession.ofAccessGrant(session, accessGrant); ``` #### 3. Create a Solid Client To access the resource with access grants, create a [SolidSyncClient](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/solid/SolidSyncClient.html) or [SolidClient](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/solid/SolidClient.html) using the [AccessGrantSession](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/accessgrant/AccessGrantSession.html): ```java SolidSyncClient client = SolidSyncClient.getClient().session(agSession); ``` #### 4. Access the Resource Use the [SolidSyncClient.send()](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/solid/SolidSyncClient.html#send\(com.inrupt.client.Request,com.inrupt.client.Response.BodyHandler\)) method to access the non-RDF resources and [SolidSyncClient.read()](https://api.docs.inrupt.com/docs/developer-tools/api/java/inrupt-client/latest/com/inrupt/client/solid/SolidSyncClient.html#read\(java.net.URI,java.lang.Class\)) method to read RDF resources. For example, the following code uses the client associated with ExamplePrinter and the access grants to read the image file (a Non-RDF resource) at the resource URL: ```java SolidNonRDFSource resource = client.read(URI.create("https://storage.example.com/some/resource"), SolidNonRDFSource.class).toCompletableFuture().join(); ``` {% hint style="info" %} If you receive an `HTTP 403 Forbidden` error, check that you have [enabled the use of access grants for the resource](https://docs.inrupt.com/sdk/java-sdk/access-requests-and-grants/..#enable-use-of-access-grants). {% endhint %}