Overview

Page Summary

• The Digital Credentials Provisioning API revolves around three main resources: Device (a unique physical device and identity key), Proofing (user identity verification), and Credential (the digital credential itself).

• Devices are represented by the physical Android device and a unique public/private identity key pair, which is used for secure communication and device identity verification with the Issuer.

• Proofing involves users submitting identity evidence, like photos and videos, which Issuers review to decide on identity verification, and a proofing status can be Pending, Accepted, Rejected, Challenged, Canceled, Revoked, or Expired.

• A Credential represents the virtual version of a physical credential tied to a specific device, and can be provisioned, updated, and have varying statuses like ProvisionPending, Active, Suspended, Revoked, or Deleted.

• Mobile Security Objects (MSOs), signed by the Issuer, are used in combination with a credential to prove to relying parties that the credential originated from the Issuer, and are discarded after use.

The Digital Credentials Provisioning API is organized by three main resource models:

Resource	Description
Device	A unique instance of a physical device and identity key.
Proofing	The process of proving a user’s identity before issuing a Credential.
Credential	The VDC itself.

As an Issuer, you are responsible for creating and managing these resources throughout the lifecycle of an VDC.

Assumptions

The primary assumption this API makes is the use of the Android Identity Credential API by the device for storing VDCs defined by ISO/IEC 18013-5.

Note: Any method that references MobileDriversLicense is specific to mDL. Other methods are agnostic of the document type.

Resource models

Device

In the Digital Credentials Provisioning API model, a device does not simply represent an Android-powered device where a user manages their VDC using the Google Wallet app. Instead, it is represented as a combination of the following:

• The physical, Android-powered device.
• A public/private key pair (referred to as an “identity key”).
  • The public key is used by the Issuer to verify a device’s identity.
  • The private key is stored in the device’s secure storage.

When making API calls, a device and credential combination is identified by a device reference ID (the deviceReferenceId property).

Note: The device reference ID is not the same as the device ID or ANDROID_ID. Two different credentials on the same physical device will have different identity keys and device reference IDs.

The first time a device communicates with an Issuer, it is given a unique nonce (to prevent replay attacks and ensure freshness). The nonce is signed by the device’s identity key and embedded in the certificate containing the identity key. Going forward, the certificate can be used to verify the device with the Issuer.

For more information on the certificate, see the Android IdentityCredential documentation.

If you model this resource as a database table, it would look similar to the following. Note that the identityKey property would be the public key value.

Proofing

A proofing represents the combination of the following:

• The evidence provided by a user to prove their identity
• The decision made by the Issuer given the supplied evidence

Proofing is specific to the type of credential the user is requesting. When provisioning an VDC, a user supplies photographs of their physical identity document and a video of their profile. The video is used by Google to calculate the likelihood that the video is a real person. The result provided by Google to Issuers is referred to as a “liveness score.” Additional proofing methods will be added as new credential types are supported.

The possible statuses for a proofing are listed in the following table.

Status	Description	Final state
Pending	The Issuer has not yet made a decision.	No
Accepted	The Issuer has decided the evidence is satisfactory.	No
Rejected	The Issuer has decided the evidence was not satisfactory.	Yes*
Challenged	The Issuer needs more information to make a decision.	No
Canceled	The user has canceled the proofing.	Yes
Revoked	The Issuer has revoked the proofing.	Yes*
Expired	The user did not complete the challenge in time.	Yes

Statuses marked with an asterisk (*) may be non-final in cases where a human reviewer makes a mistake and updates the status manually.

The following state diagram describes the possible status flows:

In some cases, Issuers may not be able to make a decision given the initial evidence. To help make the decision, users can be challenged to supply additional information or evidence to the Issuer. Examples of challenges include responding to mail letters, visiting an Issuer website, or submitting additional evidence.

If you model this resource as a database table, it would look similar to the following.

Note: This is not an exhaustive schema, but illustrated for comprehension purposes. Another table to track challenges, and a way to link a proofing to a device is likely also needed in the issuer's system.

Credential

A credential represents the virtual version of the physical credential for a specific device. Every time a virtual credential is provisioned to a physical device, it is assigned a credential ID. If the same physical credential is provisioned to different devices, it will have a different credential ID each time. Likewise, if a credential is provisioned to a device, deleted, and provisioned again to the same device, it would have a different credential ID.

When the details of a user’s credential change (such as an address change for a identity document), these details must be updated for any associated virtual credentials. A single credential can have different versions corresponding to such changes. The current version is tracked using a credential version ID.

Note: The credential ID will not change throughout the lifecycle of a credential. However, the credential version ID may change.

In order to present a credential to a relying party, the device must first retrieve mobile security objects (MSO) from the issuer. An MSO contains digests of the credential that have been signed by the Issuer. An MSO is created from an auth key, a public key generated and signed by the device’s identity key. The auth key effectively binds the MSO to the device. The combination of the MSO and credential proves to relying parties that the credential originated from the Issuer.

Note: MSOs are discarded after use. Devices maintain a pool of MSOs, refreshing the pool as needed.

Once a credential is provisioned onto a device, the device must send a ProofOfProvisioning object back to the Issuer. This notifies the Issuer that the credential has been successfully provisioned to the device and stored in the device’s secure storage.

Note: As an Issuer, you should not release MSOs for a credential until you have received a ProofOfProvisioning for that credential. This applies to updates to a credential as well.

A credential can have the following statuses:

Status	Description
ProvisionPending	The credential has been released to Google Wallet, but proof of provisioning has not been returned to the Issuer. Credentials are moved to this status any time the credential version ID changes. No MSOs will be released for this credential.
Active	The credential has been released to Google Wallet and proof of provisioning has been returned to the Issuer. MSOs are available to the credential.
Revoked	The issuer has permanently revoked the credential. No MSOs will be released for this credential. Google Wallet will not present a credential in this state.
Deleted	The user or Google Wallet has permanently deleted the credential from the device. No MSOs will be released for this credential. Google Wallet will not present a credential in this state.

The following state diagram describes the possible status flows:

If you model this resource as a database table, it would look similar to the following.

Note: This is not an exhaustive schema, but illustrated for comprehension purposes. Another table to track MSOs, and a way to link a credential to a device and or proofing is likely also needed in the issuer's system.