Get started with the Verify with Wallet API

Request the entitlement

If you’d like to use the Verify with Wallet API, you’ll need to have an entitlement assigned to your developer account. Account Holders in the Apple Developer Program can submit an entitlement request for the Verify with Wallet API. Requests are granted per bundle ID (the app’s unique identifier) and assigned entitlements can only be used with the single binary associated with the bundle ID.

In order to be eligible, your app must:

• Require an equivalent age or identity verification process for each user who obtains the same goods or services for the relevant jurisdiction; and
• Be in one of the following categories:

• Access (Physical Security)
• Air Travel
• Alcohol Purchase (Order Ahead and Delivery)
• Car Rental
• Financial Services
• Gig Economy
• Government Services
• Healthcare
• Hospitality
• Insurance
• Scooter Rentals
• Ticketing

These categories provide developers with a secure, privacy-centric alternative to traditional verification methods, reducing the need for users to manually upload personal information. To express interest in additional categories for future consideration, please describe how you’d like to use the Verify with Wallet API in the entitlement request form.

Information you’ll need to provide

App information

• App name
• Bundle ID (the app’s unique identifier)
• App Store or TestFlight URL
• App Clip App ID (if applicable)
• Description of the good or service being offered through your app that requires age or identity verification
• Screenshots of your identity or age verification process for users that do not use an ID in Apple Wallet

Data available to request

Usage information

• Describe the good or service being offered through your app that requires age or identity verification and how verification is addressed today.
• Upload screenshots of your proposed age or identity verification process for users that use ID in Apple Wallet, as well as the existing or proposed age or identity verification process for users that do not use ID in Apple Wallet.
• Provide the URL link to your app’s privacy policy, and the privacy policy of each third party that will collect or retain any types of data for Verify with Wallet.

Implement the API

Once you receive the Verify with Wallet API entitlement, you can invoke the Verify with Wallet API in the PassKit framework and specify the information you’re requesting. To offer a consistent experience across apps, the API provides a set of buttons you can use in your app when you need to ask for identity or age verification. Tapping a button displays a sheet that describes your request and lets people agree to share their information or cancel. If they agree, your app will receive an encrypted response which it passes to your server for decryption and verification.

Localized buttons

Documentation, videos, and resources

• IDs in Apple Wallet: privacy and security overview
• Human Interface Guidelines: Identity verification
• Requesting identity data from a Wallet pass
• Verifying Wallet identity requests
• PKIdentityDriversLicenseDescriptor
• PKIdentityNationalIDCardDescriptor
• Sample data and simulator keys
• Wallet and Apple mDL Developer Integrator profile
• Developer forums
• Feedback Assistant

Issuing authority certificates

In order to verify a payload from a user’s issuing authority, you’ll need to download and use its IACA certificate from their website.

US

• IACA certificate for Arizona
• IACA certificate for California
• IACA certificate for Colorado
• IACA certificate for Georgia
• IACA certificate for Hawaii
• IACA certificate for Iowa
• IACA certificate for Maryland
• IACA certificate for Montana
• IACA certificate for New Mexico
• IACA certificate for Ohio
• IACA certificate for Puerto Rico

Japan

• IACA certificate for Government of Japan

  Note: Per relevant law, identity verification services that utilize My Number cards must undergo a functional certification process. For details, view the Digital Agency of Japan’s website.

Frequently asked questions

Using the API

Once I’ve been granted the entitlement, how do I set up my developer account and Xcode project?

In the "Certificates, Identifiers, & Profiles" section of the Apple Developer website:

1. Create a merchant ID. If you already have a merchant ID you use for Apple Pay, you can reuse it here.
2. Create an "Identity Access Certificate" for your merchant ID. This will show up in the "Identity" tab in the "Edit or Configure a Merchant ID" page.
   1. Note that the private key of the encryption certificate will be used by your server to decrypt the encryptedData returned from the API.
3. Add the "In App Identity Presentment" capability to your App ID. This will appear in the "Additional Capabilities" tab of the "Edit your App ID Configuration" page.
4. Add the 'In App Identity Presentment Merchant IDs' capability to your App ID and select the associated Merchant IDs.
5. Generate a new provisioning profile with these changes.

You'll also need to manually configure your app's entitlements plist file.

Entitlement #1:

Choose document-type you want to be granted entitlement via submit an entitlement request.

"com.apple.developer.in-app-identity-presentment": {
    "document-types": [
        "us-drivers-license"
    ],
    "elements": [
        "given-name",
        "family-name",
        "portrait",
        "address",
        "issuing-authority",
        "document-expiration-date",
       	"document-number",
        "driving-privileges",
        "age",
        "date-of-birth"
    ]
},

Filter the list of entitlements to just the ones you requested through the entitlement request.

Entitlement #2:

"com.apple.developer.in-app-identity-presentment.merchant-identifiers": [
    “your-merchant-id-goes-here”
]

Note that you must add this entitlement even if you're using the same merchant ID for Apple Pay. Apple Pay's com.apple.developer.in-app-payments entitlement is NOT recognized for identity verification.

For browser-based online presentment, we intend to support the mDoc request API as developed in the W3C, pending its final definition, in a way that also enables presentment of conforming identity credentials from third party applications that meet appropriate privacy and security guidelines.

How can I test my use of the API?

There are several ways to test your use of the API:

• Using the iOS simulator. The simulator comes preloaded with mock data you can use to test your integration with the API. For details on the keys and other resources needed to validate responses from the simulator’s mock data, download the Sample data and simulator keys bundle.
• On an iOS device. When you install the Wallet and Apple mDL Developer Integrator profile, the API will return mock data containing a real device signature but no issuer signature.
• Test sample. The Sample data and simulator keys bundle contains a sample response with all of the keys and certificates needed to validate it. Use this to test your response validation logic.

Which descriptor should I use to request ID data?

To request ID data, use PKIdentityNationalIDCardDescriptor

Note: Elements specific to Japan can only be retrieved when the region API is set to JP.