Overview

Ver.iD Issuance uses the OAuth authorization code flow with PKCE. The OAuth scope is issuance.

Use issuance when your application needs to place a credential in a customer's digital identity wallet. Studio defines the credential structure. Your server supplies the values for one customer through an issuance intent.

Before you start

Create and activate an issuance in Ver.iD Studio. The configuration must contain:

• At least one supported digital identity wallet.
• The credentials and attributes that can be issued.
• An exact redirect URI for your application.
• An issuance mapping, or the UUIDs of all configured attributes.
• An OAuth client secret for the server integration.

Copy the issuer URI and client identifier from the active issuance's Configuration tab. Use the key from an OAuth secret attached to the issuance as the client secret. The SDK uses the issuer URI to discover the authorization, token, intent, and signing-key endpoints.

Studio configuration and intents

Studio configuration defines what can be issued. It includes the digital identity wallets, credentials, attributes, redirect URIs, brands, mappings, and consent information.

The intent defines one issuance run and supplies its credential values. Issuance always requires an intent. You cannot create an issuance URL without its intent_id.

Creating the intent also returns an issuance_run_uuid. Store this identifier with your business transaction so the run and its final result can be correlated.

The intent must contain exactly one payload form:

• A mapping object whose keys match an active issuance mapping.
• A data array containing an attribute UUID and value for every configured attribute.

Use one format only. Do not send mapping and data together.

All required credential values must be present. The intent cannot add credentials or attributes that are not part of the active Studio configuration.

The intent can also control settings for this run:

These settings do not change the active Studio configuration.

Flow

1. Your server validates the values that will be placed in the credential.
2. Your server creates a random state, a PKCE code verifier, and an S256 code challenge.
3. Your server creates an intent through the discovered intent_endpoint. It sends the credential payload, code challenge, and client secret.
4. Ver.iD returns an intent_id and an issuance_run_uuid.
5. Your server creates an authorization URL with the issuance scope, registered redirect URI, state, code challenge, and intent_id.
6. Your application redirects the customer to Ver.iD. The customer selects a digital identity wallet and reviews the credential.
7. The digital identity wallet accepts and stores the credential.
8. Ver.iD returns the customer to the registered redirect URI with an authorization code and the original state.
9. Your server confirms the returned state and exchanges the code with the matching PKCE verifier and client secret.
10. Ver.iD returns a signed issuance result as the access_token. Your server verifies and decodes it before recording the outcome.

Issuance result

The issuance access token is a signed result JWT. It contains the issuanceRunUuid and output for the completed digital identity wallet interaction. The output records the credential and attribute identifiers, their values, and their issuance status.

Use the run UUID to connect this result to the intent created by your application. Verify the JWT before trusting any result or status.

Production security

Production issuance uses a confidential server-side client. Use @ver-id/node-client to create the intent, generate the authorization URL, finalize the callback, and verify the result.

• Keep the client secret and PKCE verifier outside browser code.
• Confirm state before exchanging the authorization code.
• Validate and authorize credential values before creating the intent.
• Do not write credential values or result tokens to application logs.
• Use shared storage for state and PKCE data when the application runs on multiple server instances.
• Use decode with assertIssuanceV1JwtPayload before reading the result.

See Start an issuance for the complete SDK example.

Supported protocol