/verify
Endpoint#
New in version 2.0.
Starting in version 2.0, ESS supports an authorization mechanism based on access requests and grants. In 2.0, the access requests and grants are serialized as a Verifiable Credentials (VCs).
To support access requests and grants, ESS provides a verification service for these VCs.
/verify
Endpoint#
The ESS VC service provides the following endpoint for VC verification:
https://vc.<ESS Domain>/verify
To verify a VC, clients can send the verification request to the endpoint:
Method: |
|
---|---|
Content-Type |
|
Endpoint: |
|
Payload: |
Verification request object. See Input: Verifiable Credential for details. |
The ESS VC service’s /verify
endpoint (also referred to as the
Verifier on this page) implements the verify portion of the VC API
specification 1.
Verification Checks#
The Verifier performs the following verification checks on Verifiable Credentials (VCs):
Checks the authenticity of the VCs. Specifically, the Verifier performs Ed25519 signature suite 2020 verifications.
Checks that the VCs have not been revoked.
Checks that the VCs have not expired.
In addition, the Verifier performs the following Solid checks on the VCs:
Field |
Description |
---|---|
|
When validating a Solid access request, the VC’s
type
field must include "SolidAccessRequest" .When validating a Solid access grant, the VC’s
type
field must include "SolidAccessGrant" . |
|
The VC’s |
|
The VC’s |
Input: Verifiable Credential#
The Verifier endpoint (/verify
) accepts a document of the
form:
{
"verifiableCredential": <Verifiable Credential to verify>,
"options": <options>
}
verifiableCredential
accepts a VC JSON-LD document.
For details, see:
Output: Verification Results#
The Verifier returns a JSON object:
{
"checks": [
"proof",
"credentialStatus",
"expirationDate"
],
"errors": [],
"warnings": []
}
checks
lists the checks performed during verification.Note
The
expirationDate
check only occurs if an expiration date is present in the VC.errors
lists any errors that occurred during verification.warnings
lists any warnings that occurred during verification.
Example#
The following is a sample access request VC:
{
"@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"
]
}
To verify the VC, post the following payload, where the
"verifiableCredential"
field is set to the VC to be verified, to
the Verifier endpoint (/verify
):
{
"verifiableCredential": {
"@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"
]
}
}
Upon successful verification, the endpoint returns the following:
{
"checks": [
"proof",
"credentialStatus"
],
"errors": [],
"warnings": []
}
Note
Since the expirationDate
is not present in the input VC, the
expirationDate
check did not occur, and thus is omitted from the
output.
- 1
The VC API specification is in Draft status. Features based on draft specifications are subject to change.