Overview

Ver.iD Disclosures uses the OAuth authorization code flow with PKCE. The OAuth scope is disclosure.

Use a disclosure when your application needs verified customer information without using the result to create a login session. For login, use Authentication instead.

Before you start

Create and activate a disclosure in Ver.iD Studio. The configuration must contain:

• At least one supported digital identity wallet.
• The credentials and attributes you want the customer to share.
• An exact redirect URI for your application.
• An output mapping when your application needs stable claim names.

Copy the issuer URI and client identifier from the active disclosure's Configuration tab. The SDK uses the issuer URI to discover the authorization, token, intent, and signing-key endpoints.

Studio configuration and intents

Studio configuration applies to every run of the disclosure. It includes the digital identity wallets, attributes, redirect URIs, brands, mappings, and consent information.

An intent applies to one run only. It is bound to the client and its PKCE code challenge. Creating an intent does not change the active Studio configuration or the attributes that the disclosure requests.

A disclosure intent is optional. Start the disclosure directly when the Studio configuration already contains everything you need. See Start a disclosure for both options.

Flow

1. Your application creates a random state, a PKCE code verifier, and an S256 code challenge.
2. When needed, your application creates a disclosure intent through the discovered intent_endpoint.
3. Your application creates an authorization URL with the disclosure scope, registered redirect URI, state, and code challenge. It also includes the intent identifier when an intent was created.
4. Your application redirects the customer to Ver.iD.
5. The customer selects a digital identity wallet and reviews the requested information.
6. The digital identity wallet asks the customer to share the configured attributes.
7. Ver.iD returns the customer to the registered redirect URI with an authorization code and the original state.
8. Your application confirms the returned state and exchanges the code with the matching PKCE verifier. A confidential client also authenticates with its client secret.
9. Ver.iD returns a signed disclosure result as the access_token.
10. Your application verifies and decodes the result before using its claims.

The disclosure access token is a result JWT. It is not an OpenID Connect ID token and must not be used as a login token.

Mappings

A disclosure mapping converts attributes from different digital identity wallets into stable claim names. For example, multiple wallets can supply a first name through different source attributes while your application always reads firstName.

The verified JWT can contain both forms of output:

Only request and retain information your application needs. Treat every disclosed value as customer data.

Client options

Use @ver-id/browser-client for a browser integration. It stores the state and PKCE verifier in browser storage and can start a direct or intent-based flow.

Use @ver-id/node-client when the flow starts or finishes on your server. Keep the client secret on the server. When the application runs on multiple instances, use shared storage for the state and PKCE verifier.

In both cases, use the SDK's finalize method to validate the callback and exchange the authorization code. Use decode with assertDisclosureV1JwtPayload to verify the result JWT before reading it.

Supported protocol