Clarification of `GET /credentials` endpoint

[kezike]

Is this endpoint supposed to return all credentials from an issuer associated with a holder in an inbox-like fashion? If so, I have some follow-up questions:

• Can issuers enable credential search via query parameters or some other mechanism? One idea that comes to mind is to accept a payload at this endpoint that includes a field to specify conditions for credential fields via JSONPaths? Examples of this form of filtering are littered throughout the Presentation Exchange spec. The only issue is that such a design would require a request body, which would necessitate an HTTP method other than GET, unless we somehow enable a search/filter mechanism via an intermediate exchange step.
• Is the expectation to use the OAuth 2.0 token (or some other auth mechanism) to identify the holder or should this request be the terminating end of an exchange workflow that begins with a DIDAuth flow?
• Should issuers enable paging via query parameters or the like?

[kezike]

I believe I have gained some understanding of this endpoint at least as it pertains to the second point. The way that exchanges are currently defined, it seems like this endpoint would not necessarily need to be called as part of an exchange workflow with DID Auth, but rather that it would fetch credentials that have already been issued to a DID via the /credentials/issue endpoint. As such, wallets would not need to perform DID Auth, since that would have already been done in the past and they will only pass verification during presentation if they control the subject DID. As such, OAuth seems to be the sole authentication responsibility for this endpoint (as for the others). Are these assumptions accurate?

[ottonomy]

+1 to defining a pagination pattern for any list endpoint.

[msporny]

The group discussed this on the 2023-06-20 telecon:

@PatStLouis noted that this could be used to get a list of credentials or a list of all issued credentials. It is not clear how this endpoint should be used. There was a discussion about what the endpoint should return when it is called. If you are an issuer coordinator, you might call this endpoint (on the issuer service) to get all credentials that you issued. If you are a holder coordinator, you might call this endpoint (on the issuer coordinator) to get all credentials that were issued to you. If you are a holder coordinator, you might call this endpoint (on the holder service) to get all of the credentials that you have stored in your digital wallet.

For example, if you are a holder and you get a presentation request, you would want to call this endpoint (and filter based on the presentation request) to get the VCs that could be used to respond to the presentation request.

Should issuers enable paging via query parameters or the like?

Should filtering be supported on this endpoint? Yes. This endpoint might be the wrong thing for filtering POST /credentials/query (or POST /credentials) so that it could take a query object as the POST body. We discussed whether or not query parameters should be used and it seemed like query parameters would work for simple use cases, but not for the most complex use cases. It also seemed like passing a presentation request directly through to the query engine might be the most effective way of re-using a common query language format.

Querying a credential database based on a presentation request, and querying a credential database for issuer management of credentials. So this might be broken up into "responding to a presentation request" and "managing a set of credentials that have been issued" and "managing a set of credentials/presentations that have been derived".

Should pagination be supported on responses? Yes (because there could be thousands of responses). The pagination could be an optional feature.

Is the expectation to use the OAuth 2.0 token (or some other auth mechanism) to identify the holder or should this request be the terminating end of an exchange workflow that begins with a DIDAuth flow?

If this endpoint is on any of the Services, then use of some authz mechanism is presumed.

The group tried to clarify what this endpoint might be, but did not have the creators of this endpoint on the call. We still lack clarity on the purpose of this endpoint.

[msporny]

The group discussed this on the 2024-02-27 telecon.

@dlongley suggested that we reserve the endpoint, but remove it from the spec until it can be defined more properly. @jandrieu noted that the endpoint might be a bad idea because it's on the issuer endpoint and we have workflows/exchanges to provide this functionality to a holder. @dlongley noted that if we wanted to keep this in the spec, it should be used for administrative functions. It shouldn't be used by holders/verifiers -- that functionality should go through exchange mechanism.

A PR should be opened to remove this endpoint from the specification until there is more implementer interest in the functionality.