/issue Endpoint

Added 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:

• Users must be authenticated. The endpoint supports the use of either Solid-OpenID Connect (OIDC) access token or, starting in version 2.1, UMA token.

• Starting in 2.2.1,

  • 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 [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:

• Users must be authenticated. The endpoint supports the use of either Solid-OpenID Connect (OIDC) access token or, starting in version 2.1, UMA token.

• Starting in 2.2.1, for access requests, users must use an application whose Client ID is allowed by the INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSREQUEST setting.

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. Added 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:

• VC Issuer API (OpenAPI specification).

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:

• Users must be authenticated. The endpoint supports the use of either Solid-OpenID Connect (OIDC) access token or, starting in version 2.1, UMA token.

• Starting in 2.2.1, for access grants, users must use an application whose Client ID is allowed by the INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSGRANT setting.

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. Added 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:

• VC Issuer API (OpenAPI specification).

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:

• VC Issue Credential API specification

• VC Issuer API (OpenAPI specification)

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.

Single ResourceContainer and Its ContentsContainer Only

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.

Single ResourceContainer and Its Contents GrantContainer Only Grant

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

[1]

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