Method: vdc.provisionMobileSecurityObjects

An endpoint to provision a credential.

HTTP request

POST https://example.issuer.com/api/v1/vdc/provisionMobileSecurityObjects

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestMetadata": {
    object (RequestMetadata)
  },
  "deviceReferenceId": string,
  "credentialId": string,
  "authKeys": [
    {
      object (AuthKey)
    }
  ],
  "proofOfProvisioning": {
    object (ProofOfProvisioning)
  },
  "deviceEncryptionKey": {
    object (DeviceEncryptionKey)
  },
  "credentialVersionId": string
}
Fields
requestMetadata

object (RequestMetadata)

The metadata about the request, required in all requests.
deviceReferenceId

string

The id that corresponds to the device and the identity key associated with the device. This is NOT a device id, meaning that if the user were to have two separate credentials on the same device, this id would differ between them.

This id is supplied in all requests, and can be used to correlate requests.
credentialId

string

An opaque identifier representing a specific credential provisioned to a device.

Ex: UUID
authKeys[]

object (AuthKey)

A list of x509 certificates needing to be certified, so that they can be used as mobile security objects. Each certificate is signed by the device credential key.
proofOfProvisioning

object (ProofOfProvisioning)

An object from the device that proves the credential was properly provisioned. See the object definition for more details on the structure of this.

Note: This object is only provided the first time mobile security objects are provisioned after the credential has been provisioned. When this method is used for MSO refreshes, this will not be provided.
deviceEncryptionKey

object (DeviceEncryptionKey)

An object containing the device's ephemeral encryption key and associated metadata. This key is used for encrypting a value back to the device. This object may not be provided in the sandbox environment during onboarding, indicating the issuer should return plaintext data. This should always be set in the production environment.
credentialVersionId

string

The credential version id that the device currently has. This SHOULD NOT be used to provision mobile security objects for old versions of credentials. If this does not match the most current version provisioned in the issuer's record, an ErrorResponse with InvalidState should be returned instead.

Response body

A response containing the result of provisioning mobile security objects.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "responseMetadata": {
    object (ResponseMetadata)
  },
  "mobileSecurityObjects": [
    {
      object (MobileSecurityObject)
    }
  ]
}
Fields
responseMetadata

object (ResponseMetadata)

The metadata about the response, required in all responses.
mobileSecurityObjects[]

object (MobileSecurityObject)

A list of MobileSecurityObjects that are ready. This list may be empty if no MobileSecurityObjects are currently ready.

AuthKey

An x509 certificate, signed by the device credential key, that is to be cerified by the issuer.

These are retrieved by the wallet from the Android Identity Credential API, and are documented further at https://developer.android.com/reference/android/security/identity/IdentityCredential#getAuthKeysNeedingCertification()

JSON representation 
{

  // Union field presencetype can be only one of the following:
  "encryptedData": {
    object (EncryptedData)
  },
  "unencryptedValue": string
  // End of list of possible types for union field presencetype.
}
Fields
Union field presencetype. An oneof indicating how the AuthKey is being presented. presencetype can be only one of the following:
encryptedData

object (EncryptedData)

The encrypted value and encryption metadata necessary to decrypt the value.
unencryptedValue

string

The base64 encoded value of the AuthKey.

ProofOfProvisioning

A COSE_Sign1 structured, signed by the device credential key, that proves the related credential was correctly provisioned to the secure storage on the device.

This structure is defined by the Android Identity Credential API, and is documented further at https://developer.android.com/reference/android/security/identity/WritableIdentityCredential#personalize(android.security.identity.PersonalizationData)

JSON representation 
{

  // Union field presencetype can be only one of the following:
  "encryptedData": {
    object (EncryptedData)
  },
  "unencryptedValue": string
  // End of list of possible types for union field presencetype.
}
Fields
Union field presencetype. An oneof indicating how the ProofOfProvisioning is being presented. presencetype can be only one of the following:
encryptedData

object (EncryptedData)

The encrypted value and encryption metadata necessary to decrypt the value.
unencryptedValue

string

The base64 encoded value of the ProofOfProvisioning.

MobileSecurityObject

An object that encapsulates digests calculated from each data element included in the credential. This is represented as static auth data, which is the required format for the Android Identity Credential library. See this for details on static auth data construction.

JSON representation 
{
  "expirationTimeMillis": string,

  // Union field presencetype can be only one of the following:
  "encryptedData": {
    object (EncryptedData)
  },
  "unencryptedValue": string
  // End of list of possible types for union field presencetype.
}
Fields
expirationTimeMillis

string (int64 format)

A timestamp representing when the mobile security object expires. The timestamp is represented as the number of milliseconds since the Unix epoch.
Union field presencetype. An oneof indicating how the credential is being presented. presencetype can be only one of the following:
encryptedData

object (EncryptedData)

The encrypted value and encryption metadata necessary to decrypt the value.
unencryptedValue

string

The base64 encoded value of the credential.