First draft of OpenId4VCI-S2S by GarethCOliver · Pull Request #753 · openid/OpenID4VCI

GarethCOliver · 2026-06-16T16:54:23Z

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:

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

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

Sakurann · 2026-06-22T20:00:28Z

+
+.# 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.


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.

do we want to change terminology to Verifiable Digital Credentials..?

Sakurann · 2026-06-22T20:03:12Z

+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].


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

"contract" did not feel descriptive enough

"protocol"? It's really a sequence of API calls, no?

Actually, it's probably both: "a set of APIs and a protocol".

Sakurann · 2026-06-22T20:05:46Z

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


why redefine what is already defined in VCI..? because calling it a VDC is very important?

Sakurann · 2026-06-22T20:07:58Z

+CredentialInstanceId:
+:  A unique identifier at an Issuer for a particular Credential Dataset on a particular Wallet Client Instance.


this looks like a parameter name... I'd suggest either define "Credential Instance Identifier" or remove CredentialInstanceId from terminology.

Sakurann · 2026-06-22T20:10:35Z

+VerificationId:
+:  An identifier generated by the Issuer for a particular verification session. Must be unique for a given SessionId.


same comment as for CredentialInstanceId. looks like a parameter name... I'd suggest either define "verification Identifier" or remove it from terminology.

Sakurann · 2026-06-22T20:12:33Z

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


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

We really need some term to cover the first phase where the WSK is established and the Issuer determines the eligibility of Issuance of the Credentials. Due to the broad range of types of credentials that can be issued, it's naturally a pretty inclusive step.

Other names that have come up in small group discussion:

User Authentication

Enrollment

Proofing

This is functionally the same as what occurs in IAE. I guess we could call it 'Interactive Authorization' but that is also an awful name IMO so.

Leaving comment open to have naming debate in call today, be good to start with a name that people are somewhat in agreement with, even if we can change later.

Note from group: kinda has to be something generic. Some preference for 'Enrollment'. Will open an issue to track name choice and leave as is for now.

Sakurann · 2026-06-22T20:13:02Z

+SessionId:
+:  A globally unique identifier associated with a particular Wallet Client Instance, persistent throughout the issuance process.


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.

This reads a bit dangerous

Suggested change

SessionId:

: A globally unique identifier associated with a particular Wallet Client Instance, persistent throughout the issuance process.

SessionId:

: A globally unique identifier associated with a particular Issuance process between a Wallet Client Instance and an Issuer, persistent throughout the issuance process.

Sakurann · 2026-06-22T20:23:51Z

+
+At a high level the protocol works in two phases; Verification and Credential Management.
+
+Verification is as follows:


Suggested change

Verification is as follows:

Issuer verifies Wallet Client Instance in the following steps:

Sakurann · 2026-06-22T20:24:26Z

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


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.

Sakurann · 2026-06-22T20:25:09Z

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


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.

Sakurann · 2026-06-22T20:25:51Z

+  - 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:


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:

Sakurann · 2026-06-22T20:28:09Z

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


I'd rather we define all endpoints upfront before using them in the sentence

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.

deshmukhrajvardhan · 2026-06-23T20:18:36Z

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


should this be "Wallet Client Instance"?

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.

Sakurann · 2026-06-24T21:16:13Z

+
+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:


what's the purpose of this phase?

Sakurann · 2026-06-24T21:17:28Z

+
+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: 


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 · 2026-06-24T21:18:58Z

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


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?

Sakurann · 2026-06-24T21:21:07Z

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


why can't this be the same endpoint like with IAE?

It could be. The design trade-offs are:

There is a (non-zero) stand-up cost for endpoints

polymorphic endpoints can be harder to reason about

separating endpoints can make analytics and monitoring easier when you have distinct expected behavior for each endpoint.

I (personally) think having non-polymorphic endpoints is better. It is harder/impossible for IAE to split their endpoint (because it is attempting to build on oauth, which has a single endpoint as you are meant to only call it once with the same payload), so at least (IMO) IAE is making a necessary compromise.

As part of harmonizing with canonical VCI we could consider merging endpoints for consistence, but there are likely to be sufficient other differences that we may be better merging messages on level down (this is why the VerificationDataRequest/Response Schemas exist).

Leaving topic open for further discussion

Sakurann · 2026-06-24T21:22:29Z

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


what's the difference of these two endpoints?

provision returns what data sets (as identifier) the Wallet Client Instance can have issued. Get returns the particular VDC instances for a given credential data set instance.

Sakurann · 2026-06-24T21:23:28Z

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


why can't this be one endpoint implemented by Both like Credential management endpoint? like Verification management endpoint or something?

It's not bi-directional because the Issuer can't tell the Wallet server to cancel an in-progress verification, it just tell the Wallet about the result.

The Cancel step is mostly there for clean-up purposes.

In the Credential Lifecycle case, we want to be able to initiate the state changes from both sides and still continue the management of the credential which is a good reason for it to have the bi-directional.

At the end of the day they are all kinda notifications, so we could just make notify bi-directional, but we currently don't have enough different types to justify that. Worth thinking about though.

Sakurann · 2026-06-24T21:24:21Z

+
+### KeyData
+
+All keys are communicated between the Wallet and Issuer using this common key structure.


is this JWK..? Field where?

to be consistent with already defined client_public_key, keyType should probably be key_type.
attestations is very generic, key_attestation is what is meant?

Sakurann · 2026-06-24T21:28:26Z

+- Via a back-channel call from the Issuer Server to the Wallet Server
+  - Though this is currently out of scope of this specification


Good question: we could put it in scope. I left it as out of scope as it is out of scope of canonical VCI, but I guess we do have a channel...

dpostnikov

Some preliminary thoughts, questions, and editorial tweaks.

dpostnikov · 2026-06-26T02:43:27Z

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


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.

Why "on web"?

'Auth on web' is coming from VCI/IAE, it's referring to a flow where you redirect to an issuer website, perform to the auth and then redirect back.

Issue #757 is tracking defining our set of verification types, which we should also likely unify with IAE.

dpostnikov · 2026-06-26T02:58:28Z

+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].


Actually, it's probably both: "a set of APIs and a protocol".

dpostnikov · 2026-06-26T03:04:32Z

+| 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 |


What does it mean? Cannot be used?

INACTIVE, INACTIVE_IN_PROGRESS, or PENDING?

A state change is occurring, so currently unknown (basically a try-again-later). It should only be relevant for particular complex credential sets.

dpostnikov · 2026-06-26T03:05:44Z

+| UNLINKED         | Credential removed from device                  |
+| IN_PROCESS       | Provisioning or lifecycle operation in progress |
+| CANCELLED        | Credential permanently invalidated              |
+| UNKNOWN          | Status cannot be determined                     |


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?

dpostnikov · 2026-06-26T08:50:24Z

+|-----------------------------|---------------|-------------------------------------------------|
+| PROVISIONING_SUCCESS        | Wallet Server | Credential successfully provisioned to device   |
+| PROVISIONING_FAILURE        | Wallet Server | Credential provisioning failed                  |
+| LIFECYCLE_SUCCESS           | Wallet Server | Lifecycle action completed                      |


how different is it from the events below?

dpostnikov · 2026-06-26T08:51:59Z

+| eventDetails         | object             | **TYPE DEPENDENT**: Implementation-specific details dependent on the eventType.   |
+| extensions           | object             | **OPTIONAL**: Implementation-specific extension fields.                           |
+
+### Event Types


Should we include a credential lifecycle section to ensure we are on the same page?

INACTIVE or PENDING... Maybe there is another spec we can refer to...

Can draw something like this in ASCII, of course.

Created #772 to track this. In practice when I've drawn these in the past they often end up every state able to transition to every other state and so are a bit infeasible (and so a representative example of primary flows is more useful).

dpostnikov · 2026-06-26T09:13:24Z

+
+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}


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}

Co-authored-by: Dima Postnikov <dima@postnikov.net>

Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com>

Co-authored-by: Dima Postnikov <dima@postnikov.net>

GarethCOliver · 2026-06-30T18:25:01Z

+
+- An Issuer Server operated by the Issuer
+- A Wallet Server operated by the Wallet Provider
+- A Wallet Client provided by the Wallet Provider and under the control of the


Update this to be less normative of what it is, but be precise about capabilities and the mental model.

Sakurann · 2026-06-30T20:50:56Z

+
+### Error Types
+
+This specification defines the following error types:


why do error types need to be URNs..?

Sakurann · 2026-06-30T20:54:00Z

+
+## Content Reference {#content-reference}
+
+This section details how large content can be passed by-reference to a downloadable URL, rather than in-band.


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 by value.

by reference vs by value are the terms usually used i think

Sakurann · 2026-06-30T20:54:58Z

+
+## Content Reference {#content-reference}
+
+This section details how large content can be passed by-reference to a downloadable URL, rather than in-band.


also, content of what? fields below are fields of what? please define clearly

c2bo · 2026-07-02T20:43:57Z

+SessionId:
+:  A globally unique identifier associated with a particular Wallet Client Instance, persistent throughout the issuance process.


This reads a bit dangerous

Suggested change

SessionId:

: A globally unique identifier associated with a particular Wallet Client Instance, persistent throughout the issuance process.

SessionId:

: A globally unique identifier associated with a particular Issuance process between a Wallet Client Instance and an Issuer, persistent throughout the issuance process.

c2bo · 2026-07-02T20:47:50Z

+
+#### Replay Protection
+
+This endpoint is protected against replay attacks through a signed nonce mechanism. The wallet produces a digital signature over the sessionId using the walletSigningKey and includes this signature as the verificationNonce field in the request.


I might be wrong, but given the current definitions, how are we guaranteeing freshness / preventing replay - I don't see an issuer provided input currently (since sessionID is potentially long-lasting)?

c2bo · 2026-07-02T20:53:30Z

+
+## Server Authentication {#server-authentication}
+
+All endpoints MUST use mutual TLS (mTLS) as the authentication method between the Wallet and Issuer Servers, as described by [@!RFC8705]. Both servers present X.509 client certificates during the TLS handshake. Certificate management is outside of scope of this specification.


We probably want to bind between SessionId and `server authentication?

Suggested change

All endpoints MUST use mutual TLS (mTLS) as the authentication method between the Wallet and Issuer Servers, as described by [@!RFC8705]. Both servers present X.509 client certificates during the TLS handshake. Certificate management is outside of scope of this specification.

All endpoints MUST use mutual TLS (mTLS) as the authentication method between the Wallet and Issuer Servers, as described by [@!RFC8705]. Both servers present X.509 client certificates during the TLS handshake. Certificate management is outside of scope of this specification.

Issuers MUST associate a SessionId with the mTLS client identity that created it and reject requests for that SessionId from any other identity.

GarethCOliver added the server-to-server label Jun 16, 2026

GarethCOliver commented Jun 16, 2026

View reviewed changes

Comment thread s2s/openid-4-verifiable-credential-issuance-server-2-server.md Outdated

dpostnikov reviewed Jun 22, 2026

View reviewed changes

Comment thread s2s/openid-4-verifiable-credential-issuance-server-2-server.md Outdated

GarethCOliver added 3 commits June 22, 2026 05:46

Fix examples to return 'STATUS'

88244d6

Fix: Wallet Instance to Wallet Client Instance

339b48b

minor fixes

1439a2f

Sakurann reviewed Jun 22, 2026

View reviewed changes

Add diagrams for examples

39ed378

GarethCOliver force-pushed the s2s branch from 97eccfe to 39ed378 Compare June 23, 2026 14:59

GarethCOliver added 2 commits June 23, 2026 08:06

Update terminology section to reference OpenID4VCI

9a88d93

for strictly unchanged definitions.

re-write initial overview

b535be5

re-written the original overview to be more of a high level description of the flow.

deshmukhrajvardhan reviewed Jun 23, 2026

View reviewed changes

GarethCOliver commented Jun 24, 2026

View reviewed changes

Comment thread s2s/openid-4-verifiable-credential-issuance-server-2-server.md Outdated

minor fix

cce76dd

Sakurann reviewed Jun 24, 2026

View reviewed changes

Comment thread s2s/openid-4-verifiable-credential-issuance-server-2-server.md Outdated

Sakurann reviewed Jun 24, 2026

View reviewed changes

Sakurann reviewed Jun 25, 2026

View reviewed changes

dpostnikov reviewed Jun 26, 2026

View reviewed changes

GarethCOliver commented Jun 30, 2026

View reviewed changes

Comment thread s2s/openid-4-verifiable-credential-issuance-server-2-server.md Outdated

GarethCOliver and others added 3 commits June 30, 2026 08:28

Apply suggestion from @GarethCOliver

bfbd27e

Apply suggestion from @GarethCOliver

4e2d7f8

Apply suggestion from @dpostnikov

e238c0e

Co-authored-by: Dima Postnikov <dima@postnikov.net>

GarethCOliver commented Jun 30, 2026

View reviewed changes

Comment thread s2s/openid-4-verifiable-credential-issuance-server-2-server.md Outdated

GarethCOliver and others added 2 commits June 30, 2026 08:38

Apply suggestion from @GarethCOliver

ce3e619

Apply suggestion from @Sakurann

3cb5348

Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com>

Apply suggestion from @Sakurann

957fee3

Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com>

GarethCOliver commented Jun 30, 2026

View reviewed changes

Comment thread s2s/openid-4-verifiable-credential-issuance-server-2-server.md

GarethCOliver and others added 7 commits June 30, 2026 09:29

Apply suggestion from @GarethCOliver

103f9d6

Apply suggestion from @Sakurann

0b648a5

Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com>

Apply suggestion from @Sakurann

1dfc9b3

Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com>

Apply suggestion from @Sakurann

1af8778

Co-authored-by: Kristina <52878547+Sakurann@users.noreply.github.com>

Update s2s/openid-4-verifiable-credential-issuance-server-2-server.md

76c93fe

Co-authored-by: Dima Postnikov <dima@postnikov.net>

Update s2s/openid-4-verifiable-credential-issuance-server-2-server.md

7cdff9d

Co-authored-by: Dima Postnikov <dima@postnikov.net>

Apply suggestion from @dpostnikov

b0062c4

Co-authored-by: Dima Postnikov <dima@postnikov.net>

GarethCOliver commented Jun 30, 2026

View reviewed changes

Sakurann reviewed Jun 30, 2026

View reviewed changes

c2bo reviewed Jul 2, 2026

View reviewed changes


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

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

		CredentialInstanceId:
		: A unique identifier at an Issuer for a particular Credential Dataset on a particular Wallet Client Instance.

		VerificationId:
		: An identifier generated by the Issuer for a particular verification session. Must be unique for a given SessionId.

		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.

		SessionId:
		: A globally unique identifier associated with a particular Wallet Client Instance, persistent throughout the issuance process.


		At a high level the protocol works in two phases; Verification and Credential Management.

		Verification is as follows:

	Verification is as follows:
	Issuer verifies Wallet Client Instance in the following steps:

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

	- This process is potentially asynchronous, while the Issuer evaluates the outcome.
	- This process is can be 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:
	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.


		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:


		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:

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

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


		### KeyData

		All keys are communicated between the Wallet and Issuer using this common key structure.

		- Via a back-channel call from the Issuer Server to the Wallet Server
		- Though this is currently out of scope of this specification

	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.


		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}

Uh oh!

Conversation

GarethCOliver commented Jun 16, 2026

Uh oh!

Uh oh!

Uh oh!

Sakurann Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sakurann Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sakurann Jun 22, 2026 •

edited

Loading

Sakurann Jun 24, 2026 •

edited

Loading


		### Error Types

		This specification defines the following error types:


		## Content Reference {#content-reference}

		This section details how large content can be passed by-reference to a downloadable URL, rather than in-band.


		#### Replay Protection

		This endpoint is protected against replay attacks through a signed nonce mechanism. The wallet produces a digital signature over the sessionId using the walletSigningKey and includes this signature as the verificationNonce field in the request.


		## Server Authentication {#server-authentication}

		All endpoints MUST use mutual TLS (mTLS) as the authentication method between the Wallet and Issuer Servers, as described by [@!RFC8705]. Both servers present X.509 client certificates during the TLS handshake. Certificate management is outside of scope of this specification.