Ctrl+K
Archived docs. ESS 2.0 has reached end of life.

/issue Endpoint#

New in version 2.0.

Starting in version 2.0, ESS supports an authorization mechanism based on access requests and grants.

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

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:

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://vc.<ESS DOMAIN>/credentials/v1"
    ],
    "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>
      }
    }
  }
}

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; e.g., "https://vc.<ESS DOMAIN>/credentials/v1".

  • credentialSubject.hasConsent must include the following fields:

    mode

    Set to a single ACL Mode or an array of ACL Modes where the Modes are:

    • "http://www.w3.org/ns/auth/acl#Read"

    • "http://www.w3.org/ns/auth/acl#Write"

    • "http://www.w3.org/ns/auth/acl#Append"

    hasStatus

    Set to the following value: "https://w3id.org/GConsent#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.

Input: Optional Fields#

You can also include:

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

    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 uses 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 does not specify an expirationDate. That is, if access is granted, the access grant has no expiration until it is revoked by the owner.

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:

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://vc.<ESS DOMAIN>/credentials/v1"
    ],
    "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>
      }
    }
  }
}

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://vc.<ESS DOMAIN>/credentials/v1".

  • credentialSubject.providedConsent must include the following fields:

    mode

    Set to a single ACL Mode or an array of ACL Modes; e.g., "http://www.w3.org/ns/auth/acl#Read"

    hasStatus

    Must be set to the following value: "https://w3id.org/GConsent#ConsentStatusExplicitlyGiven"

    forPersonalData

    Set to the IRI of the target resource or an array of IRIs if specifying multiple target resources.

    isProvidedTo [1]

    Set to the WebID of the agent to whom access is being granted.

Input: Optional Fields#

You can also include:

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

    If expirationDate is included in the access grant 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 uses 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 does not specify an expirationDate. That is, the access grant has no expiration until it is revoked by the resource owner.

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://w3id.org/security/suites/ed25519-2020/v1"

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

  • "https://vc.<ESS Domain>/credentials/v1"

credentialStatus

The value is an object with the following fields and values:

Field

Value

"id"

"https://vc.<ESS Domain>/status/<credential>#<idx>"

"revocationListCredential

"https://vc.<ESS Domain>/status/<credential>"

"revocationListIndex

"<idx>"

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

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 requested access expires; i.e., becomes invalid.

The field only appears if any of the following conditions are met:

  • The field is included in the payload to the Issuer endpoint.

  • ESS Access Grant service has INRUPT_VC_MAX_DURATION set.

If both conditions are met, then the Issuer calculates a date based on the INRUPT_VC_MAX_DURATION value and uses the earlier of the calculated date and the specified expirationDate.

If only the field is included in the payload, the Issuer uses the input value.

If only INRUPT_VC_MAX_DURATION is set, the Issuer calculates the expiration date based on the duration value.

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 is an example access request that meets the ESS’ access request shape. In the request, the agent requestingrabbit is asking for read access to owliverowner’s resource https://storage.<ESS DOMAIN>/<xyz>/some/private/data:

{
  "credential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://vc.<ESS DOMAIN>/credentials/v1"
    ],
    "credentialSubject": {
      "hasConsent": {
        "mode": [ "http://www.w3.org/ns/auth/acl#Read" ],
        "hasStatus": "https://w3id.org/GConsent#ConsentStatusRequested",
        "isConsentForDataSubject": "https://id.<ESS DOMAIN>/owliverowner",
        "forPersonalData": [
          "https://storage.<ESS DOMAIN>/<owliversPodIdentifier>/getting-started/readingList/myList"
        ]
      }
    }
  }
}

When the request is posted to the Issuer endpoint (issue), the Issuer returns a signed VC for the access request:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1",
    "https://w3id.org/vc-revocation-list-2020/v1",
    "https://vc.<ESS DOMAIN>/credentials/v1"
  ],
  "credentialStatus": {
    "id": "https://vc.<ESS DOMAIN>/status/SkbE#0",
    "revocationListCredential": "https://vc.<ESS DOMAIN>/status/SkbE",
    "revocationListIndex": "0",
    "type": "RevocationList2020Status"
  },
  "credentialSubject": {
    "hasConsent": {
      "mode": [
        "http://www.w3.org/ns/auth/acl#Read"
      ],
      "hasStatus": "https://w3id.org/GConsent#ConsentStatusRequested",
      "isConsentForDataSubject": "https://id.<ESS DOMAIN>/owliverowner",
      "forPersonalData": [
        "https://storage.<ESS DOMAIN>/<owliversPodIdentifier>/getting-started/readingList/myList"
      ]
    },
    "id": "https://id.<ESS DOMAIN>/requestingrabbit",
  },
  "id": "https://vc.<ESS DOMAIN>/vc/xxxxxx...",
  "issuanceDate": "2021-10-25T03:21:58.512Z",
  "issuer": "https://vc.<ESS DOMAIN>",
  "proof": {
    "created": "2021-10-25T03:21:58.708Z",
    "domain": "solid",
    "proofPurpose": "assertionMethod",
    "proofValue": "xxxxxx........",
    "type": "Ed25519Signature2020",
    "verificationMethod": "https://vc.<ESS DOMAIN>/key/xxxxx...."
  },
  "type": [
    "VerifiableCredential",
    "SolidAccessRequest"
  ]
}

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 is an example access grant that meets the ESS’ access grant shape. In the access grant, the resource owner owliverowner grants requestingrabbit read access to owliverowner’s resource https://ess.example.com/owliverowner/private/somedata:

{
  "credential": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://vc.<ESS DOMAIN>/credentials/v1"
    ],
    "credentialSubject": {
      "providedConsent": {
        "mode": "http://www.w3.org/ns/auth/acl#Read",
        "hasStatus": "https://w3id.org/GConsent#ConsentStatusExplicitlyGiven",
        "forPersonalData": [
           "https://storage.<ESS DOMAIN>/<owliversPodIdentifier>/getting-started/readingList/myList"
         ],
        "isProvidedTo": "https://id.<ESS DOMAIN>/requestingrabbit"
      }
    }
  }
}

When the access grant is posted to the Issuer endpoint (issue), the Issuer returns a signed VC for the access grant:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1",
    "https://w3id.org/vc-revocation-list-2020/v1",
    "https://vc.<ESS DOMAIN>/credentials/v1"
  ],
  "credentialStatus": {
    "id": "https://vc.d<ESS DOMAIN>/status/xCZZ#0",
    "revocationListCredential": "https://vc.d<ESS DOMAIN>/status/xCZZ",
    "revocationListIndex": "0",
    "type": "RevocationList2020Status"
  },
  "credentialSubject": {
    "providedConsent": {
      "mode": "http://www.w3.org/ns/auth/acl#Read",
      "hasStatus": "https://w3id.org/GConsent#ConsentStatusExplicitlyGiven",
      "forPersonalData": [
        "https://storage.<ESS DOMAIN>/<owliversPodIdentifier>/getting-started/readingList/myList"
      ],
      "isProvidedTo": "https://id.<ESS DOMAIN>/requestingrabbit"
    },
    "id": "https://id.<ESS DOMAIN>/owliverowner"
  },
  "id": "https://vc.<ESS DOMAIN>/vc/xxxxxx...",
  "issuanceDate": "2021-10-31T02:58:04.459Z",
  "issuer": "https://vc.<ESS DOMAIN>",
  "proof": {
    "created": "2021-10-31T02:58:05.218Z",
    "domain": "solid",
    "proofPurpose": "assertionMethod",
    "proofValue": "xxxxxx........",
    "type": "Ed25519Signature2020",
    "verificationMethod": "https://vc.<ESS DOMAIN>/key/xxxxx...."
  },
  "type": [
    "VerifiableCredential",
    "SolidAccessGrant"
  ]
}
On this page