/issue Endpoint

ESS supports an authorization mechanism based on Access Requests and Grants. The Access Requests and Access Grants include the specific access mode (e.g. Read, Write, Append), the resources to access, etc.

Important

An Access Request for a Container, by default, also applies to the Container’s descendants, unless explicitly specified otherwise in the request (See inherit: false).
An Access Grant for a Container, by default, also applies to the Container’s descendants, unless explicitly specified otherwise in the grant (See inherit: false).

ESS serializes the Access Requests and Grants as Verifiable Credentials (VCs) and provides an endpoint that issues Access Requests and Grants as VCs.

`/issue` Endpoint

The ESS Access Grant Service provides an endpoint for issuing Access Requests and Grants as VCs. By default, it takes this form:

https://vc.<ESS Domain>/issue

Note

To access the /issue endpoint:

Users must be authenticated. The endpoint supports the use of either Solid-OpenID Connect (OIDC) access token or UMA token.
For Access Requests, users must use an application whose Client ID is allowed by the INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSREQUEST setting.
For Access Grants, users must use an application whose Client ID is allowed by the INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSGRANT setting.

The ESS Access Grant Service’s /issue endpoint (also referred to as the Issuer on this page) implements the issuer portion of the VC API specification.

The VC API specification is in Draft status. Features based on draft specifications are subject to change.

Access Request VCs

To acquire a VC for an Access Requests, clients can send their requests to the Issuer endpoint (/issue).

Method

POST

Content-Type

application/json

Endpoint

https://vc.<ESS Domain>/issue

Payload

Access Request object that conforms to the ESS Access Request Shape.

Input: Access Request Shape

ESS defines a shape constraint (shown below in JSON-LD representation) for the Access Requests:

{
  "credential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://schema.inrupt.com/credentials/v1.jsonld"
    ],
    "credentialSubject": {
      "hasConsent": {
        "mode": <Access Mode URL | Array of Access Mode URLs>,
        "hasStatus": "https://w3id.org/GConsent#ConsentStatusRequested",
        "isConsentForDataSubject": <Resource Owner WebID>,
        "forPersonalData": <Resource URL | Array of Resource URLS>,
        "inherit": <Optional. true|false>
      }
    }
  }
}

With this shape constraint, Access Requests sent to the endpoint must conform to the shape. That is, specific to the Issuer:

@context must include the ESS Access Grant VC Context "https://schema.inrupt.com/credentials/v1.jsonld" and the standard VC context "https://www.w3.org/2018/credentials/v1".

Note

The ESS Access Grant VC Context can be found at "https://schema.inrupt.com/credentials/v1.jsonld".

credentialSubject.hasConsent
- Must include:
  mode
  Set to a single ACL Mode or an array of ACL Modes where the Modes are:
  "Read"
  "Write"
  "Append"
  hasStatus
  Set to the following https://w3id.org/GConsent status: "ConsentStatusRequested".
  isConsentForDataSubject
  Set to the WebID of the resource owner.
  forPersonalData
  Set to the URL of the target resource or an array of URLs if specifying multiple target resources.
  If a target resource is a Container, the requested access, by default, encompasses both the Container and its descendants.
  See the inherit field description (below).
- May include the optional:
  inherit
  Set to a boolean to determine whether the access request on a Container should also encompass the resources within the Container (i.e., the Container’s descendants). That is, set to:
  true if the requested access on a Container encompasses both the Container and its descendants.
  false if the requested access on a Container is only for the Container itself.
  Default is true; i.e., if omitted, the access request on a Container encompasses both the Container and its descendants.

Input: Additional Fields

The following fields are optional:

credentialSubject.hasConsent.forPurpose field that contains the purpose for the access. For its value, specify a URL or an array of URLs indicating the purpose.
credentialSubject.inbox is set to the URL of the requesting agent’s inbox. If included, the field can only have one inbox.
credentialSubject.id field that contains the requesting agent’s WebID.
{% hint style="info" %} Regardless of the credentialSubject.id field’s inclusion or its value in the request, the ESS Access Grant service issues a signed VC with the credentialSubject.id value set to the requesting agent’s WebID. That is, the Issuer overrides the field’s value if set. If unset, the Issuer adds the field. {% endhint %}
issuanceDate field that contains the start date and time when the requested access is to take effect; i.e., becomes valid.
If omitted, the Issuer specifies the date and time it issues the VC.
expirationDate field that contains the date and time at which the requested access expires; i.e., becomes invalid. This field value is compared with an expiration date calculated by the ESS Access Grant service and the earlier of the two dates is used.
If expirationDate is included in the request and
- ESS Access Grant service has INRUPT_VC_MAX_DURATION set,
  - The Issuer calculates a date based on the duration value and uses the earlier of the calculated date and the specified expirationDate.
- ESS Access Grant service does not have INRUPT_VC_MAX_DURATION set,
  - The Issuer calculates the expiration date using P365D (365 days) as the duration, and uses the earlier of the calculated date and the specified expirationDate.
If expirationDate is not included in the request and
- ESS Access Grant service has INRUPT_VC_MAX_DURATION set,
  - The Issuer calculates the expiration date based on the duration value.
- ESS Access Grant service does not have INRUPT_VC_MAX_DURATION set,
  - The Issuer uses a default value of P365D (365 days) for the expirationDate.

Access Grant VCs

The resource owner can deny or grant the Access Request. To acquire a VC for the Access Grants, clients can send the resource owner’s requests to the Issuer endpoint (/issue).

Method

POST

Content-Type

application/json

Endpoint

https://vc.<ESS Domain>/issue

Payload

Access Grant object that conforms to ESS Access Grant Shape.

Access Grant Effective Period

An active (i.e., not revoked) access grant is effective:

Starting from its issuanceDate to its expirationDate, and
While its credentialSubject.id (the grantor) remains a resource owner.

Input: Access Grant Shape

ESS defines a shape constraint (shown below in JSON-LD representation) for the Access Grant:

{
  "credential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://schema.inrupt.com/credentials/v1.jsonld"
    ],
    "credentialSubject": {
      "providedConsent": {
        "mode": <Access Mode IRI | Array of Access Mode IRIs>,
        "hasStatus": "https://w3id.org/GConsent#ConsentStatusExplicitlyGiven",
        "forPersonalData": <ResourceIRI | Array of Resource IRIS>,
        "isProvidedTo": <WebID>,
        "inherit": <Optional. true|false>
      }
    }
  }
}

With the shape constraint, Access Grants sent to the endpoint must conform to the shape. That is, specific to the Issuer:

@context must include the ESS Access Grant VC Context; e.g., "https://schema.inrupt.com/credentials/v1.jsonld".

Note The ESS Access Grant VC Context can be found at "https://schema.inrupt.com/credentials/v1.jsonld"

credentialSubject.providedConsent
- Must include:
  mode
  Set to a single ACL Mode or an array of Modes; e.g., "Read" or [ "Read", "Write"].
  hasStatus
  Must be set to the following https://w3id.org/GConsent value: "ConsentStatusExplicitlyGiven".
  forPersonalData
  Set to the IRI of the target resource or an array of IRIs if specifying multiple target resources.
  If a target resource is a Container, the Access Grant, by default, encompasses both the Container and its descendants. See the inherit field description (below).
  isProvidedTo
  Set to the WebID of the agent to whom access is being granted.
- May include the optional:
  inherit
  Set to a boolean to determine whether the Access Grant on a Container should also apply to the resources within the Container (i.e., the Container’s descendants). That is, set to:
  true if the Access Grant on a Container applies to both the Container and its descendants.
  false if the Access Grant on a Container is only for the Container itself.
  Default is true; i.e., if omitted, the Access Grant on a Container applies to both the Container and its descendants.

Input: Additional Fields

The following fields are optional:

credentialSubject.providedConsent.forPurpose field that contains the purpose for the access. For its value, specify a URL or an array of URLs indicating the purpose.
issuanceDate field that contains the start date and time when the access grant is to take effect; i.e., becomes valid. The value can be in the future.
If omitted, the Issuer specifies the date and time it issues the VC.
expirationDate field that contains the date and time at which the access grant expires; i.e., becomes invalid. This field value is compared with an expiration date calculated by the ESS Access Grant service and the earlier of the two dates is used.
If expirationDate is included in the payload and
- ESS Access Grant service has INRUPT_VC_MAX_DURATION set,
  - The Issuer calculates a date based on the duration value and uses the earlier of the calculated date and the specified expirationDate.
- ESS Access Grant service does not have INRUPT_VC_MAX_DURATION set,
  - The Issuer calculates the expiration date using P365D (365 days) as the duration, and uses the earlier of the calculated date and the specified expirationDate.
If expirationDate is not included in the access grant and
- ESS Access Grant service has INRUPT_VC_MAX_DURATION set,
  - The Issuer calculates the expiration date based on the duration value.
- ESS Access Grant service does not have INRUPT_VC_MAX_DURATION set,
  - The Issuer uses a default value of P365D (365 days) for the expirationDate.

Output: Access Request/Grant VC

When a credential payload is POSTed to the Issuer, a signed VC is returned with the following fields:

“@context”

The value is an array with the following values:

"https://www.w3.org/2018/credentials/v1"
"https://schema.inrupt.com/credentials/v1.jsonld"
"https://w3id.org/security/data-integrity/v1"
"https://w3id.org/vc-revocation-list-2020/v1"
"https://w3id.org/vc/status-list/2021/v1"
"https://w3id.org/security/suites/ed25519-2020/v1"

credentialStatus

The value is an object with the following fields and values:\
Field
Value
"id"
"https://vc.<ESS Domain>/status/<credential>#<idx>"
The URL of the revocation status for this VC.
"revocationListCredential
"https://vc.<ESS Domain>/status/<credential>"
The URL identifying the VC in the revocation list.
"revocationListIndex
"<idx>"
The bit position (i.e., the index) of the VC’s revocation status.
"type"
"RevocationList2020Status"

For more information, see RevocationList2020Status.

credentialSubject

The value is the object sent to the Issuer with the following modification:
credentialSubject.id is set to the user posting to the Issuer.

id

The value is the ID of the VC; i.e., the URL for the VC.

issuanceDate

The value is the date and time the requested access is to take effect; i.e., becomes valid.
If the field was included in the payload to the Issuer, the Issuer uses the input value.
Otherwise, if the field was not part of the payload, the Issuer uses the date and time of issuance.

issuer

The value is the ESS Access Grant Service URL; e.g., "https://vc.<ESS Domain>/".

expirationDate

The date and time at which the access request/grant expires; i.e., becomes invalid.

All issued Access Requests/Grants have an expiration date. To determine the expirationDate value, the Issuer:

Calculates an expiration date based on the INRUPT_VC_MAX_DURATION value or P365D as the default duration value if the option is not set.
If the payload specifies an expirationDate field, compares this specified value with the calculated value.
Based on the comparison, uses the earlier of the two dates as the expirationDate.

proof

Adds the proof object with the following fields and values:

Field

Value

"created"

"<DateTimestamp>"

"domain"

"solid"

"proofPurpose"

"assertionMethod"

"proofValue"

"<value>"

"type"

"Ed25519Signature2020"

"verificationMethod"

"https://vc.<ESS DOMAIN>/key/<key>"

See Ed25519 Signature 2020 for description of the fields.

type

For Access Request VCs, the type field to an array with the following two values:

"VerifiableCredential"
"SolidAccessRequest"

For Access Grant VCs, the type field to an array with the following two values:

"VerifiableCredential"
"SolidAccessGrant"

Example

Access Request

Note

Access to the Issuer endpoint (/issue) requires users to be authenticated.

The following example payloads meet the ESS’ Access Request Shape for the Issuer endpoint (/issue).

The following example assumes INRUPT_VC_MAX_DURATION is set to 90 days (P90D).

Tip It is recommended that Access Request and Access Grants have an expiration.

The following payload is asking for read access to owliverowner’s resource https://storage.<ESS DOMAIN>/<owliversRootContainer>/some/private/data:

{
  "credential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://schema.inrupt.com/credentials/v1.jsonld"
    ],
    "credentialSubject": {
      "hasConsent": {
        "mode": [ "Read" ],
        "hasStatus": "ConsentStatusRequested",
        "isConsentForDataSubject": "https://id.<ESS DOMAIN>/owliverowner",
        "forPersonalData": [
          "https://storage.<ESS DOMAIN>/<owliversRootContainer>/getting-started/readingList/myList"
        ]
      }
    }
  }
}

When requestingrabbit posts the payload to the Issuer endpoint (issue), the Issuer returns an Access Request serialized as a signed VC:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://schema.inrupt.com/credentials/v1.jsonld",
    "https://w3id.org/security/data-integrity/v1",
    "https://w3id.org/vc-revocation-list-2020/v1",
    "https://w3id.org/vc/status-list/2021/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ],
  "id": "https://vc.<ESS DOMAIN>/vc/296de1b0-380a-4b3c-8f8f-c23b96f55e2d",
  "type": [
    "VerifiableCredential",
    "SolidAccessRequest"
  ],
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2023-05-01T16:13:59.233Z",
    "domain": "solid",
    "proofPurpose": "assertionMethod",
    "proofValue": "xxxxxx........",
    "verificationMethod": "https://vc.<ESS DOMAIN>/key/xxxxx...."
  },
  "credentialStatus": {
    "id": "https://vc.<ESS DOMAIN>/status/y94G#0",
    "type": "RevocationList2020Status",
    "revocationListCredential": "https://vc.<ESS DOMAIN>/status/y94G",
    "revocationListIndex": "0"
  },
  "credentialSubject": {
    "id": "https://id.<ESS DOMAIN>/requestingrabbit",
    "hasConsent": {
      "mode": "Read",
      "forPersonalData": "https://storage.<ESS DOMAIN>/<owliversRootContainer>/getting-started/readingList/myList",
      "hasStatus": "ConsentStatusRequested",
      "isConsentForDataSubject": "https://id.<ESS DOMAIN>/owliverowner"
    }
  },
  "issuanceDate": "2023-05-01T16:13:59.044Z",
  "expirationDate": "2023-07-30T16:13:59.043962767Z",
  "issuer": "https://vc.<ESS DOMAIN>"
}

In the returned Access Request,

The credentialSubject.id contains requestingrabbit’s WebID.
The expirationDate is set to 90 days from issuance date (per INRUPT_VC_MAX_DURATION set to P90D).

Access Grant

Note

Access to the Issuer endpoint (/issue) requires users to be authenticated.

The following example payloads meet the ESS’ Access Grant Shape for the Issuer endpoint (/issue).

The following example assumes INRUPT_VC_MAX_DURATION is set to 90 days (P90D).

Tip

It is recommended that Access Request and Access Grants have an expiration.

The following payload grants requestingrabbit read access to owliverowner’s resource https://storage.<ESS DOMAIN>/<owliversRootContainer>/getting-started/readingList/myList:

{
  "credential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://schema.inrupt.com/credentials/v1.jsonld"
    ],
    "credentialSubject": {
      "providedConsent": {
        "mode": ["Read"],
        "hasStatus": "ConsentStatusExplicitlyGiven",
        "forPersonalData": [
           "https://storage.<ESS DOMAIN>/<owliversRootContainer>/getting-started/readingList/myList"
         ],
        "isProvidedTo": "https://id.<ESS DOMAIN>/requestingrabbit"
      }
    }
  }
}

When the owliverowner, the resource owner, posts the payload to the Issuer endpoint (issue), the Issuer returns an Access Grant serialized as signed VC:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://schema.inrupt.com/credentials/v1.jsonld",
    "https://w3id.org/security/data-integrity/v1",
    "https://w3id.org/vc-revocation-list-2020/v1",
    "https://w3id.org/vc/status-list/2021/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ],
  "id": "https://vc.<ESS DOMAIN>/vc/xxxxxx...",
  "type": [
    "VerifiableCredential",
    "SolidAccessGrant"
  ],
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2023-05-01T16:46:44.146Z",
    "domain": "solid",
    "proofPurpose": "assertionMethod",
    "proofValue": "xxxxxx........",
    "verificationMethod": "https://vc.<ESS DOMAIN>/key/xxxxx...."
  },
  "credentialStatus": {
    "id": "https://vc.<ESS DOMAIN>/status/VWTj#0",
    "type": "RevocationList2020Status",
    "revocationListCredential": "https://vc.<ESS DOMAIN>/status/VWTj",
    "revocationListIndex": "0"
  },
  "credentialSubject": {
    "id": "https://id.<ESS DOMAIN>/owliverowner",
    "providedConsent": {
      "mode": "Read",
      "forPersonalData": "https://storage.<owliversRootContainer>/getting-started/readingList/myList",
      "hasStatus": "ConsentStatusExplicitlyGiven",
      "isProvidedTo": "https://id.<ESS DOMAIN>/requestingrabbit"
    }
  },
  "issuanceDate": "2023-05-01T16:46:44.016Z",
  "expirationDate": "2023-07-30T16:46:44.016672206Z",
  "issuer": "https://vc.<ESS DOMAIN>"
}

In the returned Access Grant, the credentialSubject.id contains owliverowner’s WebID.

In the returned Access Grant,

The credentialSubject.id contains owliverowner’s WebID.
The expirationDate is set to 90 days from issuance date (per INRUPT_VC_MAX_DURATION set to P90D).

PreviousAccess Grant Service Next/verify Endpoint

Last updated 2 months ago