FAQ

  • Google will host signing certificates for Issuers to prevent traffic spikes, but Issuers still need to host endpoints serving those keys.

  • All mTLS certificates must be rotated yearly, and a Google representative will assist in this process.

  • All unencrypted data in API requests must be transmitted as a base64-encoded string, and each nonce used in device registration needs to be unique.

  • Issuers can use the ErrorResponse object, along with the errorDescription property in the API spec, to communicate non-business logic related rejections and errors.

  • The credentialVersionId should only be updated when the user's personal identifiable information (PII) changes, such as their name or address.

Certificates

Will devices request HPKE certificates directly from issuers?

Google will host the signing certificates for Issuers. This is to avoid traffic spikes to Issuers from devices. Issuers are still expected to host endpoints serving those keys for Google.

What is the rotation cycle for mTLS certificates?

All mTLS certificates should be rotated yearly. A Google representative will work with you to complete this activity.

API requests

What format should unencrypted parameters be in requests to the API?

All unencrypted data that is sent or received must be a base64-encoded string.

Is the device registration nonce a random string?

The nonce can be a random string. However, each nonce must be unique per request.

How do I notify Google if an unexpected error occurs while processing a request?

Issuers can use the ErrorResponse object for non-business logic based rejections and errors. Refer to the errorDescription property in the API specification.

Can a user with multiple devices add their ID/DL to all of them?

It's up to the issuer on how many devices they want to support. Each Digital ID on each device would have a different credential ID, so they could see how many credentials have been provisioned and start rejecting proofings for more or provide the user an option delete an ID from a particular device.

Is the deviceReferenceId unique?

Yes. All the 3 ids (deviceReferenceId, credentialId, proofingId) used in this API are unique.

When would the credentialVersionId change?

The credentialVersionId should be updated when the user's personal identifiable information (PII) changes (e.g., address, name, etc.). Issuers should only issue MSOs after verifying the proof of provisioning for the updated credential.

What's the average size of the proofing request?

~ 5 MB. Front and Back of the card is 1 MB each, and the Selfie is ~2.5 MB.

Is there a specific order for the expiring / new key in /getIdentityKey response when performing identity key rotations?

No, the order doesn't matter.

How do I capture a bug report on an Android device?

Refer to the Android documentation.