First draft of OpenId4VCI-S2S#753
Draft
GarethCOliver wants to merge 8 commits into
Draft
Conversation
This is the first draft of the s2s variant of credential issuance. In an early state, and still needs a lot of polish. Before this is ready to review there needs to be: - Flow Diagrams - Example flows for Credential Lifecycle Notable missing features: - Atomic Credential Sets - Specified VerificationData for common uses - Reverification - Schemas Additionally, before the first implementors draft a convergence effort with existing VCI needs to be undertaken including: - Credential Offer - IAE - Credential Endpoint - Notifications - Encryption - Issuer and Credential Metadata
GarethCOliver
commented
Jun 16, 2026
dpostnikov
reviewed
Jun 22, 2026
Sakurann
reviewed
Jun 22, 2026
|
|
||
| .# Abstract | ||
|
|
||
| This specification defines an API for the issuance and management of Verifiable Digital Credentials between a Wallet Server and Issuer Server, while enabling sensitive user data to remain confidential between a Wallet Client Instance and the Issuer. |
Collaborator
There was a problem hiding this comment.
Suggested change
| This specification defines an API for the issuance and management of Verifiable Digital Credentials between a Wallet Server and Issuer Server, while enabling sensitive user data to remain confidential between a Wallet Client Instance and the Issuer. | |
| This specification defines an API for the issuance and management of Verifiable Credentials between a Wallet Server and Issuer Server, while keeping sensitive user data confidential between a Wallet Client Instance and the Issuer without revealing it to the Wallet Server. |
Collaborator
There was a problem hiding this comment.
do we want to change terminology to Verifiable Digital Credentials..?
Sakurann
reviewed
Jun 22, 2026
Comment on lines
+31
to
+35
| This specification defines the contract between a Wallet Server and one or more | ||
| Credential Issuer Servers for credential issuance and lifecycle management. It | ||
| is credential format agnostic so Credentials can be of any format, including, | ||
| but not limited to, IETF SD-JWT VC [@I-D.ietf-oauth-sd-jwt-vc], ISO mdoc | ||
| [@ISO.18013-5], and W3C VCDM [@VC_DATA_2.0]. |
Collaborator
There was a problem hiding this comment.
Suggested change
| This specification defines the contract between a Wallet Server and one or more | |
| Credential Issuer Servers for credential issuance and lifecycle management. It | |
| is credential format agnostic so Credentials can be of any format, including, | |
| but not limited to, IETF SD-JWT VC [@I-D.ietf-oauth-sd-jwt-vc], ISO mdoc | |
| [@ISO.18013-5], and W3C VCDM [@VC_DATA_2.0]. | |
| This specification defines a set of APIs used by the Wallet Server | |
| for credential issuance and lifecycle management. It | |
| is credential format agnostic. Credentials can be of any format, including, | |
| but not limited to, IETF SD-JWT VC [@I-D.ietf-oauth-sd-jwt-vc], ISO mdoc | |
| [@ISO.18013-5], and W3C VCDM [@VC_DATA_2.0]. |
Collaborator
There was a problem hiding this comment.
"contract" did not feel descriptive enough
Collaborator
There was a problem hiding this comment.
"protocol"? It's really a sequence of API calls, no?
Collaborator
There was a problem hiding this comment.
Actually, it's probably both: "a set of APIs and a protocol".
Sakurann
reviewed
Jun 22, 2026
Comment on lines
+58
to
+59
| Credential (or Verifiable Digital Credential (VDC)): | ||
| : An instance of a Credential Configuration with a particular Credential Dataset, that is signed by an Issuer and can be cryptographically verified. An Issuer may provide multiple Credentials as separate instances of the same Credential Configuration and Credential Dataset but with different cryptographic values. In this specification, the term "Verifiable Digital Credential" is also referred to as "Credential". |
Collaborator
There was a problem hiding this comment.
why redefine what is already defined in VCI..? because calling it a VDC is very important?
Sakurann
reviewed
Jun 22, 2026
Comment on lines
+70
to
+71
| CredentialInstanceId: | ||
| : A unique identifier at an Issuer for a particular Credential Dataset on a particular Wallet Client Instance. |
Collaborator
There was a problem hiding this comment.
this looks like a parameter name... I'd suggest either define "Credential Instance Identifier" or remove CredentialInstanceId from terminology.
Comment on lines
+85
to
+86
| VerificationId: | ||
| : An identifier generated by the Issuer for a particular verification session. Must be unique for a given SessionId. |
Collaborator
There was a problem hiding this comment.
same comment as for CredentialInstanceId. looks like a parameter name... I'd suggest either define "verification Identifier" or remove it from terminology.
Comment on lines
+82
to
+83
| Verification: | ||
| : Verification in this specification refers to the process by which an Issuer determines that a Wallet Client Instance is authorized to have particular Credentials issued to it. |
Collaborator
There was a problem hiding this comment.
Verification is way too generic as a term to be defined. either be more specific "Wallet Client Instance Verification", but i'd rather not define this as a term
Comment on lines
+79
to
+80
| SessionId: | ||
| : A globally unique identifier associated with a particular Wallet Client Instance, persistent throughout the issuance process. |
Collaborator
There was a problem hiding this comment.
same comment as for CredentialInstanceId. looks like a parameter name... I'd suggest either define "Session Identifier", which is way too obvious to be defined IMHO or remove it from terminology.
| # Terminology {#terminology} | ||
|
|
||
|
|
||
| This specification defines the following terms. In the case where a term has a definition that differs, the definition below is authoritative for this specification. |
Collaborator
There was a problem hiding this comment.
why each of the following terms from VCI/VP are redefined?: Credential, Credential Configuration, Credential Issuer, Credential Format, Holder, Presentation, Wallet, etc.
Please do not redefine and simply say:
This specification uses the terms "XXX" defined by VCI , "ZZZ" defined by VP, etc.
Collaborator
There was a problem hiding this comment.
Wallet Client, Wallet Client Instance, Wallet Server are terms that seem to be most valuable to be defined in this spec
|
|
||
| At a high level the protocol works in two phases; Verification and Credential Management. | ||
|
|
||
| Verification is as follows: |
Collaborator
There was a problem hiding this comment.
Suggested change
| Verification is as follows: | |
| Issuer verifies Wallet Client Instance in the following steps: |
| Verification is as follows: | ||
|
|
||
| - The Wallet Server and Issuer Server mutually authenticate with each other using mTLS, prior to any endpoint interaction. | ||
| - As part of initiating verification of the Wallet Client Instance, the Wallet Client establishes an attested public key (WSK) which is used to authenticate payloads originating on Wallet Client. |
Collaborator
There was a problem hiding this comment.
Suggested change
| - As part of initiating verification of the Wallet Client Instance, the Wallet Client establishes an attested public key (WSK) which is used to authenticate payloads originating on Wallet Client. | |
| - As part of initiating verification of the Wallet Client Instance, the Wallet Client establishes an attested public key (WSK) which is later used to authenticate payloads originating on Wallet Client. |
| - As part of initiating verification of the Wallet Client Instance, the Wallet Client establishes an attested public key (WSK) which is used to authenticate payloads originating on Wallet Client. | ||
| - VerificationData is collected on the Wallet Client and encrypted to the Issuer Server to demonstrate the | ||
| - The Wallet Server MAY also contribute additional VerificationData | ||
| - This process is potentially asynchronous, while the Issuer evaluates the outcome. |
Collaborator
There was a problem hiding this comment.
either mark this as a to-do, or be more assertive
Suggested change
| - This process is potentially asynchronous, while the Issuer evaluates the outcome. | |
| - This process is can be asynchronous, while the Issuer evaluates the outcome. |
| - The Wallet Server MAY also contribute additional VerificationData | ||
| - This process is potentially asynchronous, while the Issuer evaluates the outcome. | ||
|
|
||
| After the Wallet Client Instance has been authenticated and is determined as authorized to have the particular Credential Instance. This works as follows: |
Collaborator
There was a problem hiding this comment.
Suggested change
| After the Wallet Client Instance has been authenticated and is determined as authorized to have the particular Credential Instance. This works as follows: | |
| After the Wallet Client Instance has been authenticated and is authorized to have the particular Credential Instance. This works as follows: |
|
|
||
| After the Wallet Client Instance has been authenticated and is determined as authorized to have the particular Credential Instance. This works as follows: | ||
|
|
||
| - The authorized CredentialInstanceIds per Credential DataSet are retrieved from the Provision Credential endpoint. Each Credential Instance MAY be managed independently. |
Collaborator
There was a problem hiding this comment.
I'd rather we define all endpoints upfront before using them in the sentence
Collaborator
There was a problem hiding this comment.
also, should be Credential Provisioning Endpoint to be more descriptive
for strictly unchanged definitions.
re-written the original overview to be more of a high level description of the flow.
| This is done as follows: | ||
|
|
||
| 1. The Wallet Client Instance generates a WSK, and the Wallet Server initiates the Verification on the Issuer Server. | ||
| 1. The Wallet provides a stable unique Session Id associated with the WSK and the Issuer provides a stable Verification Id to reference this session. |
Contributor
There was a problem hiding this comment.
should this be "Wallet Client Instance"?
Contributor
Author
There was a problem hiding this comment.
Could be, or could be the Wallet Server that generates it and provides it to the Wallet Client. It's just a UUID, so doesn't really matter.
GarethCOliver
commented
Jun 24, 2026
|
|
||
| .# Abstract | ||
|
|
||
| This specification defines an API for the issuance and management of Verifiable Digital Credentials between a Wallet Server and Issuer Server, while enabling sensitive user data to remain confidential between a Wallet Client Instance and the Issuer. |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| This specification defines an API for the issuance and management of Verifiable Digital Credentials between a Wallet Server and Issuer Server, while enabling sensitive user data to remain confidential between a Wallet Client Instance and the Issuer. | |
| This specification defines an API for the issuance and management of Verifiable Digital Credentials between a Wallet Server and Issuer Server, while keeping sensitive user data confidential between a Wallet Client Instance and the Issuer (i.e., not revealing it to the Wallet Server). |
Sakurann
reviewed
Jun 24, 2026
| 1. The Issuer Server can optionally repeat this process to trigger the collection of additional Verification. | ||
| 1. After reaching a verdict the Issuer Server updates the verification status and notifies the Wallet Server of the change. | ||
|
|
||
| On successful completion the Issuer Server now has a WSK that can be used to authenticate payloads as originating on a particular Wallet Client Instance, and have established which Credentials can be issued. |
Collaborator
There was a problem hiding this comment.
Suggested change
| On successful completion the Issuer Server now has a WSK that can be used to authenticate payloads as originating on a particular Wallet Client Instance, and have established which Credentials can be issued. | |
| On successful completion the Issuer Server now has a WSK that can be used to authenticate payloads as originating on a particular Wallet Client Instance, and have authenticated the Holder. |
Sakurann
reviewed
Jun 24, 2026
|
|
||
| On successful completion the Issuer Server now has a WSK that can be used to authenticate payloads as originating on a particular Wallet Client Instance, and have established which Credentials can be issued. | ||
|
|
||
| The Wallet retrieves the credentials as follows: |
Collaborator
There was a problem hiding this comment.
what's the purpose of this phase?
Sakurann
reviewed
Jun 24, 2026
|
|
||
| In advance of any communication, the Wallet Server and Issuer Server authenticate via mTLS, which is used at all endpoints. The Wallet Server is responsible for authenticating the Wallet Client and ensuring it is in a good state before communicating with the Issuer Server. | ||
|
|
||
| Issuance begins with a Verification phase. This phase serves two purposes: |
Collaborator
There was a problem hiding this comment.
is there issuer metadata retrieval step? How does the issuer know which credential wallet instance is asking for to know which verification data is needed?
Sakurann
reviewed
Jun 25, 2026
| The Wallet retrieves the credentials as follows: | ||
|
|
||
| 1. The Wallet Server retrieves the Credential Instance Identifiers from the Wallet Server using the Session Id and Verification Id. | ||
| 1. The Wallet Client generates proofs for Presentation Keys and signs-then-encrypts them using the WSK. The Wallet Client also creates an encryption key and signs it with the WSK. |
Collaborator
There was a problem hiding this comment.
signs-then-encrypts them using the WSK. The Wallet Client also creates an encryption key and signs it with the WSK.
WSK is used for signing and encryption? but then another encryption key is generated?
| 1. The Issuer verifies the keys originated on the correct client using the WSK, validates the proofs and creates the Credentials. The Credentials are encrypted using the Wallet Encryption Key before being sent back to the Wallet. | ||
| 1. Credential Metadata, such as display can optionally be returned as well. | ||
|
|
||
| This process is repeated to refresh the Credentials and to update them. Credentials can be managed through the following processes: |
Collaborator
There was a problem hiding this comment.
Suggested change
| This process is repeated to refresh the Credentials and to update them. Credentials can be managed through the following processes: | |
| This process is repeated to refresh the Credentials and to update them. Post initial issuance, Credentials lifecycle can be managed through the following processes: |
Comment on lines
+175
to
+176
| | Verification Initiate | /verification/initiate | Issuer | Starts the verification process for a Wallet Client Instance for a particular set of credential configurations. | | ||
| | Verification Supplement | /verification/supplement | Issuer | Provides additional verification data for an ongoing verification session. | |
Collaborator
There was a problem hiding this comment.
why can't this be the same endpoint like with IAE?
Comment on lines
+180
to
+181
| | Provision Credentials | /credential/provision | Issuer | Fetches credential instance IDs after verification approval. | | ||
| | Get Credential | /credential/get | Issuer | Retrieves the verifiable credentials for a particular credential instance. | |
Collaborator
There was a problem hiding this comment.
what's the difference of these two endpoints?
Comment on lines
+177
to
+179
| | Get Verification Status | /verification/status | Issuer | Queries the current status of a verification session. | | ||
| | Verification Notification | /verification/notify | Wallet | Allows the Issuer to notify the Wallet of a verification status change. | | ||
| | Verification Cancellation | /verification/cancel | Issuer | Cancels an ongoing verification session. | |
Collaborator
There was a problem hiding this comment.
why can't this be one endpoint implemented by Both like Credential management endpoint? like Verification management endpoint or something?
|
|
||
| ### KeyData | ||
|
|
||
| All keys are communicated between the Wallet and Issuer using this common key structure. |
Collaborator
There was a problem hiding this comment.
is this JWK..? Field where?
|
|
||
| ## Content Reference {#content-reference} | ||
|
|
||
| This section details how large content can be passed `by-reference` to a downloadable URL, rather than in-band. |
Collaborator
There was a problem hiding this comment.
we usually use `s for parameter names.
Suggested change
| This section details how large content can be passed `by-reference` to a downloadable URL, rather than in-band. | |
| This section details how large content can be passed by-reference to a downloadable URL, rather than in-band. |
|
|
||
| ### Engagement | ||
|
|
||
| There are five different flows we are considering here: |
Collaborator
There was a problem hiding this comment.
Suggested change
| There are five different flows we are considering here: | |
| There are five different flows we are considering in this specification: |
please bring this section higher. content-wise, this section is closer to the overview and relationship between the wallet and the issuer
| 1. **Issuer Initiate (Unauthed Holder)**: Holder is in an Issuer Surface (e.g. Issuer Website) but are not currently (sufficiently) authenticated. The Holder wishes to initiate a Wallet Client Instance and begin Issuance of some Credentials. | ||
| 1. **Device Migration**: Holder in a new Wallet Client Instance, but has previously performed Verification in another Wallet Client Instance. | ||
|
|
||
| All engagement is modeled as the Wallet receiving a `Credential Offer` payload from the Issuer. |
Collaborator
There was a problem hiding this comment.
Is "Credential Offer" here user in the same way as in VCI? worth mentioning earlier that that "Credential Offer" definition of VCI applies then
Suggested change
| All engagement is modeled as the Wallet receiving a `Credential Offer` payload from the Issuer. | |
| All engagement is modeled as the Wallet receiving a Credential Offer payload from the Issuer. |
Comment on lines
+343
to
+344
| - Via a back-channel call from the Issuer Server to the Wallet Server | ||
| - Though this is currently out of scope of this specification |
dpostnikov
reviewed
Jun 26, 2026
dpostnikov
left a comment
dpostnikov
left a comment
Collaborator
There was a problem hiding this comment.
Some preliminary thoughts, questions, and editorial tweaks.
| 1. The Wallet Client Instance generates a WSK, and the Wallet Server initiates the Verification on the Issuer Server. | ||
| 1. The Wallet provides a stable unique Session Id associated with the WSK and the Issuer provides a stable Verification Id to reference this session. | ||
| 1. The Wallet Client Instance collects Verification Data and signs-then-encrypts it using the WSK and the Issuer Encryption Key. | ||
| 1. Examples include digital credential presentations, auth on web, wallet collected documents and liveness/selfie checks. |
Collaborator
There was a problem hiding this comment.
Suggested change
| 1. Examples include digital credential presentations, auth on web, wallet collected documents and liveness/selfie checks. | |
| 1. Examples include digital credential presentations, authentication on web, wallet-collected documents and liveness/selfie checks. |
| 1. The Wallet provides a stable unique Session Id associated with the WSK and the Issuer provides a stable Verification Id to reference this session. | ||
| 1. The Wallet Client Instance collects Verification Data and signs-then-encrypts it using the WSK and the Issuer Encryption Key. | ||
| 1. Examples include digital credential presentations, auth on web, wallet collected documents and liveness/selfie checks. | ||
| 1. The Wallet Server optionally provides additional Verification Data and calls the Issuer Server. |
Collaborator
There was a problem hiding this comment.
Suggested change
| 1. The Wallet Server optionally provides additional Verification Data and calls the Issuer Server. | |
| 1. The Wallet Server calls The Issuer Server, passing Wallet Client-supplied Verification Data and, optionally, providing additional Wallet Server-supplied Verification Data. |
Comment on lines
+31
to
+35
| This specification defines the contract between a Wallet Server and one or more | ||
| Credential Issuer Servers for credential issuance and lifecycle management. It | ||
| is credential format agnostic so Credentials can be of any format, including, | ||
| but not limited to, IETF SD-JWT VC [@I-D.ietf-oauth-sd-jwt-vc], ISO mdoc | ||
| [@ISO.18013-5], and W3C VCDM [@VC_DATA_2.0]. |
Collaborator
There was a problem hiding this comment.
Actually, it's probably both: "a set of APIs and a protocol".
| | SUSPENDED_ISSUER | Suspended by the credential issuer | | ||
| | SUSPENDED_WALLET | Suspended by the wallet operator | | ||
| | UNLINKED | Credential removed from device | | ||
| | IN_PROCESS | Provisioning or lifecycle operation in progress | |
Collaborator
There was a problem hiding this comment.
What does it mean? Cannot be used?
INACTIVE, INACTIVE_IN_PROGRESS, or PENDING?
| | UNLINKED | Credential removed from device | | ||
| | IN_PROCESS | Provisioning or lifecycle operation in progress | | ||
| | CANCELLED | Credential permanently invalidated | | ||
| | UNKNOWN | Status cannot be determined | |
Collaborator
There was a problem hiding this comment.
Can it not find a credential? 404?
Or is it that the Wallet Client hasn't been live or synced for X period of time?
Or?
| |-----------------------------|---------------|-------------------------------------------------| | ||
| | PROVISIONING_SUCCESS | Wallet Server | Credential successfully provisioned to device | | ||
| | PROVISIONING_FAILURE | Wallet Server | Credential provisioning failed | | ||
| | LIFECYCLE_SUCCESS | Wallet Server | Lifecycle action completed | |
Collaborator
There was a problem hiding this comment.
how different is it from the events below?
| | eventDetails | object | **TYPE DEPENDENT**: Implementation-specific details dependent on the eventType. | | ||
| | extensions | object | **OPTIONAL**: Implementation-specific extension fields. | | ||
|
|
||
| ### Event Types |
Collaborator
There was a problem hiding this comment.
Should we include a credential lifecycle section to ensure we are on the same page?
Collaborator
There was a problem hiding this comment.
INACTIVE or PENDING... Maybe there is another spec we can refer to...
Can draw something like this in ASCII, of course.
| ## Wallet Client Origin {#wallet-client} | ||
|
|
||
| This specification makes use of a Wallet Signing Key to authenticate payloads originating from the Wallet Client. As part of Verification, the Wallet Signing Key signs-and-encrypts Verification Data, demonstrating to the Issuer that the Verification Data was collected in the presence of the Wallet Signing Key. How strongly that Data types the Wallet Signing Key depends on the specifics of the issuance process and is outside the scope of this specification. | ||
|
|
Collaborator
There was a problem hiding this comment.
Suggested change
| ## Wallet Client and Wallet Client Instance Trust {#wallet-client-trust} | |
| This specification delegates the decision about whether a Wallet Client, or a specific instance of it, can be trusted, and to what extent, to the Wallet Server. For example, the Wallet Server can securely verify the Wallet Client's integrity using platform-level hardware checks before executing any lifecycle actions. The exact mechanism for determining Wallet Client trust is out of scope for this specification, but must be considered by implementers. | |
|
|
||
| This specification makes use of a Wallet Signing Key to authenticate payloads originating from the Wallet Client. As part of Verification, the Wallet Signing Key signs-and-encrypts Verification Data, demonstrating to the Issuer that the Verification Data was collected in the presence of the Wallet Signing Key. How strongly that Data types the Wallet Signing Key depends on the specifics of the issuance process and is outside the scope of this specification. | ||
|
|
||
| # Privacy Considerations {#privacy-considerations} |
Collaborator
There was a problem hiding this comment.
Suggested change
| # Privacy Considerations {#privacy-considerations} | |
| ## Pre-authorization Code security measures {#preauth-security} | |
| It is important to note that anyone with a valid Pre-Authorized Code, without additional security measures, can receive a Credential from the Credential Issuer. Implementers MUST implement the mitigations most suitable to the use case. | |
| # Privacy Considerations {#privacy-considerations} |
|
|
||
| ## Asynchronous Endpoints {#asynchronous-endpoints} | ||
|
|
||
| The API is designed for the Verification and Credential endpoints to operate asynchronously. Wallet Servers MUST support responses being returned both as immediate responses, as well as asynchronously in the future. As notifications are unreliable, it's RECOMMENDED for Wallet Servers to use both notifications and polling-with-backoff to receive the results from these endpoints as quickly and reliably as possible. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The API is designed for the Verification and Credential endpoints to operate asynchronously. Wallet Servers MUST support responses being returned both as immediate responses, as well as asynchronously in the future. As notifications are unreliable, it's RECOMMENDED for Wallet Servers to use both notifications and polling-with-backoff to receive the results from these endpoints as quickly and reliably as possible. | |
| The APIs are designed so that the Verification and Credential endpoints operate asynchronously. Wallet Servers MUST support returning responses both immediately and asynchronously in the future. As notifications are unreliable, it's RECOMMENDED that Wallet Servers use both notifications and polling-with-backoff to receive results from these endpoints as quickly and reliably as possible. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is the first draft of the s2s variant of credential issuance.
In an early state, and still needs a lot of polish, creating poll request to allow visibility given the size and for S2S WG discussion.
Before this is ready to review there needs to be:
Notable missing features:
Additionally, before the first implementors draft a convergence effort with existing VCI needs to be undertaken including: