/issue Endpoint#

New in version 2.0.

Starting in version 2.0, 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 resource(s) to access, etc.

Important

Starting in version 2.1:

  • 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).

In the previous version, access request/grant applied only to the explicitly stated resource or resources in the access request/grant, regardless of whether the resource is a Container, an Resource Description Framework (RDF) Resource, or a Non-RDF Resource.

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 Verifiable Credentials. By default, it takes this form:

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

Note

To access the /issue endpoint:

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 [1].

Access Request VCs#

To acquire a VC for an access request, 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.

Note

To access the /issue endpoint for access requests:

Input: Access Request Shape#

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

{
  "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

    Starting in version 2.1, the ESS Access Grant VC Context can be found at "https://schema.inrupt.com/credentials/v1.jsonld".

    See ESS Access Grant VC Context for more information.

  • credentialSubject.hasConsent

    • Must include:

      mode

      Set to a single ACL (http://www.w3.org/ns/auth/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.

      Note

      Starting in 2.1, if a target resource is a Container, the requested access, by default, encompasses both the Container and its descendants.

      In the previous version, access request applied only to the explicitly stated resource or resources in the access request, regardless of whether the resource is a Container, an Resource Description Framework (RDF) Resource, or a Non-RDF Resource.

      See the inherit field description.

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

      New in version 2.1.

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.

    Tip

    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.

  • 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, starting in v2.2, 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, starting in v2.2, uses a default value of P365D (365 days) for the expirationDate.

See also:

Access Grant VCs#

The resource owner can deny or grant the access request. To acquire a VC for the access grant, 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.

Note

To access the /issue endpoint for access grants:

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

    Starting in version 2.1, the ESS Access Grant VC Context can be found at "https://schema.inrupt.com/credentials/v1.jsonld".

    See ESS Access Grant VC Context for more information.

  • credentialSubject.providedConsent

    • Must include:

      mode

      Set to a single ACL (http://www.w3.org/ns/auth/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.

      Note

      Starting in 2.1, if a target resource is a Container, the access grant, by default, applies to both the Container and its descendants. See the inherit field description.

      In the previous version, access grant applied only to the explicitly stated resource or resources in the access grant, regardless of whether the resource is a Container, an Resource Description Framework (RDF) Resource, or a Non-RDF Resource.

      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.

      New in version 2.1.

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, starting in v2.2, 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, starting in v2.2, uses a default value of P365D (365 days) for the expirationDate.

See also:

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" (New in v2.1)

  • "https://w3id.org/security/data-integrity/v1" (New in v2.1)

  • "https://w3id.org/vc-revocation-list-2020/v1"

  • "https://w3id.org/vc/status-list/2021/v1" (New in v2.1)

  • "https://w3id.org/security/suites/ed25519-2020/v1" (New in v2.1)

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.

Starting in v2.2, 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, starting in v2.2, 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"

See also:

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.

  • To acquire a VC for an access grant, the authenticated user must be the resource owner.

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