Skip to content

Add credential deletion section. #491

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add credential deletion section. #491

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion holder.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,9 @@ paths:
- oAuth2: []
- zCap: []
summary: Deletes a credential or verifiable credential by ID. To delete a credential that does not have credential.id set but has an associated credentialId value, pass credentialId instead.
x-expectedCaller: "Issuer Coordinator"
x-expectedCaller:
- Issuer Coordinator
- Holder Coordinator
operationId: deleteCredential
parameters:
- $ref: "./components/parameters/path/ObjectId.yml"
Expand Down
86 changes: 52 additions & 34 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -489,48 +489,49 @@ <h3>Services</h3>
network endpoints of services are defined herein.
</p>
<p>
The Issuer Service takes requests to issue VCs from authorized Issuer Coordinators
and returns well-formed, signed Verifiable Credentials. This service MUST
have access to private keys (or key services which utilize private keys)
in order to create the proofs for those VCs. The API between the Issuer
service and its associated key service is believed to be out of scope for
the VC API, but may be addressed by WebKMS or similar specifications.
The <dfn>issuer service</dfn> takes requests to issue VCs from authorized Issuer
Coordinators and returns well-formed, signed Verifiable Credentials. This
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems odd to have this Verifiable Credentials where the rest of the paragraph uses the VC abbreviation. I'm suggesting to abbreviate this one, to make the paragraph internally consistent, believing that there's a Verifiable Credentials (VCs) or similar earlier in the document. The whole document should optimally be made consistent, likely with <dfn> tags applied to the appropriate (usually first) instance and <a> tags applied to the rest, and using VC in most instances.

Suggested change
Coordinators and returns well-formed, signed Verifiable Credentials. This
Coordinators and returns well-formed, signed VCs. This

service MUST have access to private keys (or key services which utilize private
keys) in order to create the proofs for those VCs. The API between the Issuer
service and its associated key service is believed to be out of scope for the VC
API, but may be addressed by WebKMS or similar specifications.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there an appropriate link for WebKMS, to serve with <a > or [[? ]], as appropriate?

</p>
<p>
The Verifier service takes requests to verify Verifiable Credentials and
Verifiable Presentations and returns the result of checking their proofs
and status (if present). The service only checks the authenticity and
timeliness of the VC; leaving the Verifier Coordinator to finish Applying any business rules needed.
The <dfn>verifier service</dfn> takes requests to verify Verifiable Credentials
and Verifiable Presentations and returns the result of checking their proofs and
status (if present). The service only checks the authenticity and timeliness of
the VC; leaving the Verifier Coordinator to finish Applying any business rules
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
the VC; leaving the Verifier Coordinator to finish Applying any business rules
the VC; leaving the Verifier Coordinator to finish applying any business rules

needed.
Comment on lines +503 to +504
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As used here, the semicolon should separate two complete sentences. The leaving... section could be reworded to start with something like the Verifier Coordinator is left to finish support this use, but going with the comma (as I've suggested below) is the smaller change to make the sentence correct.

Suggested change
the VC; leaving the Verifier Coordinator to finish Applying any business rules
needed.
the VC, leaving the Verifier Coordinator to finish applying any necessary
business rules.

</p>
<p>
The Holder service takes requests to create Verifiable Presentations
from an optional set of VCs and returns well-formed, signed Verifiable
Presentations containing those VCs. These VPs are used with Issuers to
demonstrate control over DIDs prior to issuance and with Verifiers to
present specific VCs.
The <dfn>holder service</dfn> takes requests to create Verifiable Presentations
from an optional set of VCs and returns well-formed, signed Verifiable
Presentations containing those VCs. These VPs are used with Issuers to
demonstrate control over DIDs prior to issuance and with Verifiers to present
specific VCs.
Comment on lines +510 to +511
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
demonstrate control over DIDs prior to issuance and with Verifiers to present
specific VCs.
demonstrate control over DIDs prior to VC issuance and with Verifiers to
present specific VCs.

</p>
</section>
<section>
<h3>Status Service</h3>
<p>
The Status Service provides a privacy-preserving means for publishing
and checking the status of any Verifiable Credentials issued by the
Issuer. Implementers of verifier services are encouraged to understand the
privacy implications of checking status by referring to the respective
status specification used by the verifiable credential.
The <dfn>status service</dfn> provides a privacy-preserving means for publishing
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The <dfn>status service</dfn> provides a privacy-preserving means for publishing
The <dfn>status service</dfn> provides a privacy-preserving means of publishing

and checking the status of any Verifiable Credentials issued by the Issuer.
Implementers of verifier services are encouraged to understand the privacy
implications of checking status by referring to the respective status
specification used by the verifiable credential.
</p>
<p>
For specific mechanisms by which to manage Verifiable Credential statuses,
it's recommended to refer to external well known specifications, such as the
[[VC-BITSTRING-STATUS-LIST]].
For specific mechanisms by which to manage Verifiable Credential statuses, it's
recommended to refer to external well known specifications, such as the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
recommended to refer to external well known specifications, such as the
recommended to refer to external well-known specifications, such as the

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The word order I suggest makes it (somewhat) less likely that well-known specifications will be read as a unit, thus not referencing only specifications that relate to the .well-known space.

Suggested change
recommended to refer to external well known specifications, such as the
recommended to refer to well-known external specifications, such as the

[[VC-BITSTRING-STATUS-LIST]].
</p>
</section>
<section>
<h3>Storage Services</h3>
<p>
<strong>Storage Service (Issuer) &bull;Storage Service
(Verifier) &bull; Storage Service (Holder)
</strong>
<strong>Storage Service (Issuer) &bull;Storage Service (Verifier) &bull; Storage
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<strong>Storage Service (Issuer) &bull;Storage Service (Verifier) &bull; Storage
<strong>Storage Service (Issuer) &bull; Storage Service (Verifier) &bull; Storage

Service (Holder)
</strong>
</p>
<p>
Each actor in the system is expected to store their own verifiable
Expand All @@ -557,13 +558,13 @@ <h3>Storage Services</h3>
<section>
<h3>Workflow Service</h3>
<p>
The Workflow Service provides a way for coordinators to automate specific
interactions for specific users. Each role (Holder, Issuer, and Verifier)
can run their own Workflow Service to create and manage exchanges that
realize particular workflows. Administrators configure the workflow system
to support particular flows. Then, when the business rules justify it,
coordinators create exchanges at their Workflow Service and give authorized
access to those exchanges to any party.
The <dfn>workflow service</dfn> provides a way for coordinators to automate
specific interactions for specific users. Each role (Holder, Issuer, and
Verifier) can run their own Workflow Service to create and manage exchanges that
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Verifier) can run their own Workflow Service to create and manage exchanges that
Verifier) can run their own workflow service to create and manage exchanges that

realize particular workflows. Administrators configure the workflow system to
support particular flows. Then, when the business rules justify it, coordinators
create exchanges at their Workflow Service and give authorized access to those
exchanges to any party.
Comment on lines +566 to +567
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
create exchanges at their Workflow Service and give authorized access to those
exchanges to any party.
create exchanges at their workflow service and give access to those exchanges
to any authorized party.

</p>
</section>
<section>
Expand Down Expand Up @@ -858,7 +859,7 @@ <h4>Holder Service</h4>
that is expected to call the endpoint
</p>
<table class="simple api-component-table"
data-api-path="/credentials/derive /presentations/prove /presentations /presentations/{id}"></table>
data-api-path="/credentials/derive /credentials/{id} /presentations /presentations/{id}"></table>

<h4>Workflow Service</h4>
<p>
Expand Down Expand Up @@ -928,6 +929,23 @@ <h4>Update Status</h4>
data-api-endpoint="post /credentials/status"></div>
</section>

<section>
<h4>Delete a Specific Credential</h4>
<p>
An [=issuer service=] or a [=holder service=] might store an issued
[=verifiable credential=] for an extended period of time. When this is done,
it can be useful to delete such a [=verifiable credential=]. An [=issuer=]
might need to do so because of regulatory requirements such as
<a href="https://en.wikipedia.org/wiki/Right_to_be_forgotten">
Comment on lines +937 to +939
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
it can be useful to delete such a [=verifiable credential=]. An [=issuer=]
might need to do so because of regulatory requirements such as
<a href="https://en.wikipedia.org/wiki/Right_to_be_forgotten">
it can be useful to delete such a [=verifiable credential=]; for instance,
an [=issuer=] might need to do so because of regulatory requirements such
as <a href="https://en.wikipedia.org/wiki/Right_to_be_forgotten">

the right to be forgotten</a>. See Section [[[#deletion]]] for additional
considerations related to the removal of [=verifiable credentials=] from
systems.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 to this. We might want to consider some additional feature which would be more of a "prune" operation than a "delete", whereby the VC isn't deleted entirely, but its credentialId and any status entries information remain (information required for the application of uniqueness constraints and the maintenance of status lists, etc.).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@PatStLouis noted that deleting the VC would need to delete any "linked" information -- including possibly revoking the credential?

The group discussed some of this on the 2025-06-24 call and came to the following conclusions:

  • The difference between DELETE and "prune" is that the latter does not revoke the credential, and the former revokes the credential.
  • Deleting any "higher level" linked information is the responsibility of the issuer coordinator and not the issuer service.
  • Deleting might not be a good option if there are audit requirements (especially due to regulatory burdens).

Copy link
Contributor

@dlongley dlongley Jul 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know that an issuer instance would necessarily "know" to "revoke" (or change any other status bit for any other status "purpose") when deletion is performed.

I think an individual implementation could implement some stops/checks that would prevent deletion via a special configuration, but I don't think it would necessarily be easy to have some default behavior based solely on the "revocation" purpose. What about "suspension"? What about other custom purposes? It seems setting an expectation or special case for "revocation" would lead to more confusion with the DELETE function, not less.

I would say, instead, that we should keep the deletion operation at this level separate and simple. We should say that custom configurations can prevent deletion for any reason (including checking arbitrary status values or for other existing "linked" information) and provide an appropriate error that would signal that a client needs to run other operations using the VC API (e.g., flip status bits) in order to enable deletion. This approach would also avoid creating multiple ways / mechanisms for changing status.

</p>

<div class="api-detail"
data-api-endpoint="delete /credentials/{id}"></div>
</section>

</section>

<section>
Expand Down