# Overview

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

| Resource | Description |
|---|---|
| [Device](https://developers.google.com/wallet/identity/provisioning/api-reference#device) | A unique instance of a physical device and identity key. |
| [Proofing](https://developers.google.com/wallet/identity/provisioning/api-reference#proofing) | The process of proving a user's identity before issuing a Credential. |
| [Credential](https://developers.google.com/wallet/identity/provisioning/api-reference#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](https://developer.android.com/reference/android/security/identity/IdentityCredential)
by the device for storing VDCs defined by
[ISO/IEC 18013-5](https://www.iso.org/standard/69084.html).

> [!NOTE]
> **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]
> **Note:** The device reference ID is not the same as the device ID or [ANDROID_ID](https://developer.android.com/reference/android/provider/Settings.Secure.html#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](https://developer.android.com/reference/android/security/identity/WritableIdentityCredential#getCredentialKeyCertificateChain(byte%5B%5D)).

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.
![An example database table for a device resource.](https://developers.google.com/static/wallet/identity/provisioning/api-reference/images/device.png)

### 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:
![](https://developers.google.com/static/wallet/identity/provisioning/api-reference/images/statuses1.png)

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.
![An example database table for a proofing resource.](https://developers.google.com/static/wallet/identity/provisioning/api-reference/images/proofing.png)

> [!NOTE]
> **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]
> **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]
> **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`](https://developer.android.com/reference/android/security/identity/WritableIdentityCredential#personalize(android.security.identity.PersonalizationData))
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]
> **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:
![](https://developers.google.com/static/wallet/identity/provisioning/api-reference/images/statuses2.png)

If you model this resource as a database table, it would look similar to the
following.
![An example database table for a credential resource.](https://developers.google.com/static/wallet/identity/provisioning/api-reference/images/credential.png)

> [!NOTE]
> **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.