{ "swagger": "2.0", "info": { "title": "Digital Credentials Provisioning API - Issuer Hosted Endpoints", "description": "This includes services hosted by issuers for the Digital Credentials Provisioning API.", "version": "v1" }, "host": "vgw.googleapis.com", "schemes": ["http", "https"], "paths": { "/v1/vdc/healthCheck": { "post": { "tags": ["vgw"], "operationId": "HealthCheck", "description": "An endpoint used to test connectivity issues.", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/HealthCheckRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/HealthCheckResponse" } } } } }, "/v1/vdc/proofUser": { "post": { "tags": ["vgw"], "operationId": "ProofUser", "description": "An endpoint to proof a user for a digital credential, using an issuer specified list of evidences, and for a specific device.", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/ProofUserRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/ProofUserResponse" } } } } }, "/v1/vdc/getProofingStatus": { "post": { "tags": ["vgw"], "operationId": "GetProofingStatus", "description": "An endpoint to retrieve the current status of a proofing.", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/GetProofingStatusRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/GetProofingStatusResponse" } } } } }, "/v1/vdc/cancelProofing": { "post": { "tags": ["vgw"], "operationId": "CancelProofing", "description": "An endpoint to cancel a proofing. This proofing must be in a Pending, Challenged or Cancelled state. If not, an [invalidState](..\/ErrorResponse#InvalidState) ErrorResponse must be returned.", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/CancelProofingRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/CancelProofingResponse" } } } } }, "/v1/vdc/provisionCredential": { "post": { "tags": ["vgw"], "operationId": "ProvisionCredential", "description": "An endpoint to provision a credential.", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/ProvisionCredentialRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/ProvisionCredentialResponse" } } } } }, "/v1/vdc/provisionMobileSecurityObjects": { "post": { "tags": ["vgw"], "operationId": "ProvisionMobileSecurityObjects", "description": "An endpoint to provision a credential.", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/ProvisionMobileSecurityObjectsRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/ProvisionMobileSecurityObjectsResponse" } } } } }, "/v1/vdc/getCredentialStatus": { "post": { "tags": ["vgw"], "operationId": "GetCredentialStatus", "description": "An endpoint to retrieve the current status of a credential.", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/GetCredentialStatusRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/GetCredentialStatusResponse" } } } } }, "/v1/vdc/notifyCredentialDeleted": { "post": { "tags": ["vgw"], "operationId": "NotifyCredentialDeleted", "description": "An endpoint to notify the issuer of a credential being deleted.", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/NotifyCredentialDeletedRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/NotifyCredentialDeletedResponse" } } } } }, "/v1/vdc/getDeviceRegistrationNonce": { "post": { "tags": ["vgw"], "operationId": "GetDeviceRegistrationNonce", "description": "An endpoint to request a device registration nonce.", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/GetDeviceRegistrationNonceRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/GetDeviceRegistrationNonceResponse" } } } } }, "/v1/vdc/registerDevice": { "post": { "tags": ["vgw"], "operationId": "RegisterDevice", "description": "An endpoint to register a device with the issuer.", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/RegisterDeviceRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/RegisterDeviceResponse" } } } } }, "/v1/vdc/getIdentityKey": { "post": { "tags": ["vgw"], "operationId": "GetIdentityKey", "description": "An endpoint to retrieve the issuer's identity key.", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/GetIdentityKeyRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/GetIdentityKeyResponse" } } } } }, "/v1/vdc/getHybridEncryptionKey": { "post": { "tags": ["vgw"], "operationId": "GetHybridEncryptionKey", "description": "An endpoint to retrieve the issuer's hybrid encryption key.", "parameters": [ { "name": "body", "description": "The request body.", "in": "body", "schema": { "$ref": "#/definitions/GetHybridEncryptionKeyRequest" } } ], "responses": { "default": { "description": "Successful operation", "schema": { "$ref": "#/definitions/GetHybridEncryptionKeyResponse" } } } } } }, "definitions": { "HealthCheckRequest": { "description": "A request to an issuer, to check the health of their system.", "type": "object", "properties": { "requestMetadata": { "description": "The metadata about the request, required in all requests.", "$ref": "#/definitions/RequestMetadata" }, "clientMessage": { "description": "A message that the server will echo in the response.", "type": "string" } } }, "RequestMetadata": { "description": "The metadata about the request, required in all requests.", "type": "object", "properties": { "requestId": { "description": "An id used to identify this specific request, and should be different for every retry. This is used for debugging purposes, such as identifying requests that failed. No idempotency requirements are attached to this Ex: UUID", "type": "string" }, "version": { "description": "The version of the API being used. This should be checked against the version of the API implemented by the server, and the request should be rejected if they do not match.", "$ref": "#/definitions/Version" }, "issuerId": { "description": "The id of the issuer Google is communicating with. This can be used to quickly filter on the specific issuer's traffic while debugging. Ex: FreeFormState_ISO2Country_MDL", "type": "string" } } }, "Version": { "description": "An object representing the version of the API.", "type": "object", "properties": { "major": { "description": "The major version number of the API. Ex: for version 1.2, this would be 1", "type": "integer", "format": "int32" }, "minor": { "description": "The minor version number of the API. Ex: for version 1.2, this would be 2", "type": "integer", "format": "int32" } } }, "HealthCheckResponse": { "description": "A response to a health check, indicating a healthy system.", "type": "object", "properties": { "responseMetadata": { "description": "The metadata about the response, required in all responses.", "$ref": "#/definitions/ResponseMetadata" }, "clientMessage": { "description": "The message sent by the client, echoed by the server.", "type": "string" } } }, "ResponseMetadata": { "description": "The metadata about the response, required in all responses.", "type": "object", "properties": { "requestId": { "description": "The request id that was sent in the request. The recipient of this response must confirm that this request_id matches the one that was passed in.", "type": "string" } } }, "ProofUserRequest": { "description": "A request to proof a user for a digital credential, using a specific bundle of evidence, and for a specific device.", "type": "object", "properties": { "requestMetadata": { "description": "The metadata about the request, required in all requests.", "$ref": "#/definitions/RequestMetadata" }, "deviceReferenceId": { "description": "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.", "type": "string" }, "proofingId": { "description": "An opaque identifier representing a proofing with a specific bundle of evidence, for a specific device. Ex: UUID", "type": "string" }, "evidence": { "description": "The list of evidences needed to proof a user for a digital credential.", "type": "array", "items": { "$ref": "#/definitions/ProofingEvidence" } }, "reverificationContext": { "description": "The context for reverification proofing.", "$ref": "#/definitions/ProofUserRequestReverificationContext" } } }, "ProofingEvidence": { "description": "An object that represents a single piece of evidence.", "type": "object", "properties": { "preAuthorizationCode": { "description": "Pre-authorization code sent from the issuer.", "$ref": "#/definitions/ProofingEvidenceEvidence" } } }, "ProofingEvidenceEvidence": { "description": "An object that represents a single piece of evidence.", "type": "object", "properties": { "encryptedData": { "description": "The encrypted value and encryption metadata necessary to decrypt the value.", "$ref": "#/definitions/EncryptedData" }, "unencryptedValue": { "description": "The base64 encoded value of the evidence.", "type": "string" }, "unencryptedInteger": { "description": "Integer value of the evidence.", "type": "integer", "format": "int32" } } }, "EncryptedData": { "description": "An encrypted value and all metadata required to decrypt.", "type": "object", "properties": { "encryptedValue": { "description": "The base64 encoded, encrypted value. Max size: 65536 bytes.", "type": "string" }, "encapsulatedKey": { "description": "The base64 encoded key that was used to encrypt the encrypted value.", "type": "string" }, "signature": { "description": "The base64 encoded signature of the plaintext value appended with the recipient's public encryption key. When this is sent from the device, this will be a COSE_Sign1 object, in the ProofOfOwnership format. The \"challenge\" in this format will be SHA-256(plaintext + recipient public key). When this is sent from the issuer, this will be a standard COSE_Sign1 object with payload = SHA-256(plaintext + recipient public key). For more details on ProofOfOwnership: https:\/\/developer.android.com\/reference\/android\/security\/identity\/IdentityCredential#proveOwnership(byte[])", "type": "string" }, "recipientKeyId": { "description": "The key id of the recipient's public key that sender used to encrypt data. The value is the certificate serial number in upper-case hex encoding. This is not the key id of the encapsulated key. The device will confirm that this key id matches the key id of the key being used for decryption.", "type": "string" } } }, "ProofUserRequestReverificationContext": { "description": "The context required to trigger reverification for the credential.", "type": "object", "properties": { "credentialId": { "description": "The credential id that the reverification is performed on.", "type": "string" } } }, "ProofUserResponse": { "description": "An acknowledgement to a request to proof a user for a digital credential, that indicates the proofing is now being processed.", "type": "object", "properties": { "responseMetadata": { "description": "The metadata about the response, required in all responses.", "$ref": "#/definitions/ResponseMetadata" }, "proofingId": { "description": "The opaque identifier representing a proofing with a specific bundle of evidence, for a specific device. This is the same proof ID that was sent in the request.", "type": "string" } } }, "GetProofingStatusRequest": { "description": "A request to retrieve the current status of a proofing.", "type": "object", "properties": { "requestMetadata": { "description": "The metadata about the request, required in all requests.", "$ref": "#/definitions/RequestMetadata" }, "deviceReferenceId": { "description": "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.", "type": "string" }, "proofingId": { "description": "An opaque identifier representing a proofing with a specific bundle of evidence, for a specific device. Ex: UUID", "type": "string" } } }, "GetProofingStatusResponse": { "description": "A response containing the current status of a proofing.", "type": "object", "properties": { "responseMetadata": { "description": "The metadata about the response, required in all responses.", "$ref": "#/definitions/ResponseMetadata" }, "proofingStatus": { "description": "The current status of the proofing.", "$ref": "#/definitions/ProofingStatus" } } }, "ProofingStatus": { "description": "An object representing the different statuses a proofing can have.", "type": "object", "properties": { "pending": { "description": "A pending status, indicating that the issuer has not yet made a decision.", "$ref": "#/definitions/ProofingStatusPending" }, "accepted": { "description": "An accepted status, indicating the issuer accepted the proofing.", "$ref": "#/definitions/ProofingStatusAccepted" }, "rejected": { "description": "A rejected status, indicating the issuer has rejected the proofing.", "$ref": "#/definitions/ProofingStatusRejected" }, "challenged": { "description": "A challenged status, indicating the issuer would like the user to complete a challenge before the issuer makes a decision on the proofing.", "$ref": "#/definitions/ProofingStatusChallenged" }, "canceled": { "description": "A canceled status, indicating the user has canceled the proofing.", "$ref": "#/definitions/ProofingStatusCanceled" }, "revoked": { "description": "A revoked status, indicating the issuer has revoked the proofing.", "$ref": "#/definitions/ProofingStatusRevoked" }, "expired": { "description": "An expired status, indicating the proofing did not have a decision made (likely due to a challenge not being completed) before a deadline, set by the issuer.", "$ref": "#/definitions/ProofingStatusExpired" } } }, "ProofingStatusPending": { "description": "An object representing a pending status. This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "ProofingStatusAccepted": { "description": "An object representing an accepted proofing status.", "type": "object", "properties": { } }, "ProofingStatusRejected": { "description": "An object representing a rejected proofing status.", "type": "object", "properties": { "primaryRejection": { "description": "The primary reason why this proofing has a rejected status.", "$ref": "#/definitions/ProofingStatusRejectedRejection" }, "additionalRejections": { "description": "Additional reasons, if they exist, why the proofing has a rejected status.", "type": "array", "items": { "$ref": "#/definitions/ProofingStatusRejectedRejection" } } } }, "ProofingStatusRejectedRejection": { "description": "An object containing details about a specific rejection reason, that lead to a proofing having a rejected status.", "type": "object", "properties": { "rejectionDescription": { "description": "A description of this rejection for support reps to debug. Note that this is never shown to users. It can contain descriptive, non-sensitive text used for debugging. Warning: Do not include any PII in this message.", "type": "string" }, "issuerRejectionIdentifier": { "description": "This identifier is specific to the issuer and is generated by the issuer. It is used for debugging purposes only in order to identify the rejection. This is the identifier that the issuer knows this rejection by.", "type": "string" }, "evidenceMismatch": { "description": "Indicates the proofing was rejected due to an evidence mismatch. Examples of use: - Mismatch of app captured selfie and image in issuer's system. - Mismatch of app capture document image and image in issuer's system.", "$ref": "#/definitions/ProofingStatusRejectedRejectionEvidenceMismatch" }, "evidenceIncomplete": { "description": "Indicates the proofing was rejected due to incomplete evidence. Examples of use: - Not all required evidence was received by the issuer.", "$ref": "#/definitions/ProofingStatusRejectedRejectionEvidenceIncomplete" }, "lowRiskScore": { "description": "(DEPRECATED: use riskCheckFailure or livenessCheckFailure accordingly) Indicates the proofing was rejected due to a low risk score. Examples of use: - The wallet provided risk score is low. - The issuer has locked this user due to repeated failed attempts.", "$ref": "#/definitions/ProofingStatusRejectedRejectionLowRiskScore" }, "recordNotFound": { "description": "Indicates the proofing was rejected due to the record not existing in the issuer's system. Examples of use: - The record is not found in the issuer's system. - A specific record is opted out.", "$ref": "#/definitions/ProofingStatusRejectedRejectionRecordNotFound" }, "recordInvalid": { "description": "Indicates the proofing was rejected due to the record in the issuer's system being in an invalid state. Examples of use: - The record is in a canceled state. - The record is expired.", "$ref": "#/definitions/ProofingStatusRejectedRejectionRecordInvalid" }, "maxProvisioningsReached": { "description": "Indicates the proofing was rejected due to provisioning the document to the maximum amount of devices allowed.", "$ref": "#/definitions/ProofingStatusRejectedRejectionMaxProvisioningsReached" }, "riskCheckFailure": { "description": "Indicates the proofing was rejected due to risk score check failure. Examples of use: - The wallet provided risk score is high, which represents a high risk of fraud. - The issuer evaluates the request has a high risk of fraud.", "$ref": "#/definitions/ProofingStatusRejectedRejectionRiskCheckFailure" }, "livenessCheckFailure": { "description": "Indicates the proofing was rejected due to liveness check failure. Examples of use: - The wallet provided liveness score is low.", "$ref": "#/definitions/ProofingStatusRejectedRejectionLivenessCheckFailure" } } }, "ProofingStatusRejectedRejectionEvidenceMismatch": { "description": "An object indicating an evidence mismatch rejection.", "type": "object", "properties": { "evidenceType": { "description": "A description of the evidence that was mismatched. Used for debug purposes only.", "type": "string" } } }, "ProofingStatusRejectedRejectionEvidenceIncomplete": { "description": "An object indicating an evidence incomplete rejection.", "type": "object", "properties": { "evidenceType": { "description": "A description of the evidence that was incomplete. Used for debug purposes only.", "type": "string" } } }, "ProofingStatusRejectedRejectionLowRiskScore": { "deprecated": true, "description": "An object indicating a low risk score rejection. This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "ProofingStatusRejectedRejectionRecordNotFound": { "description": "An object indicating a record not found rejection. This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "ProofingStatusRejectedRejectionRecordInvalid": { "description": "An object indicating an invalid record rejection.", "type": "object", "properties": { "invalidityReason": { "description": "A description of why the record is invalid.", "type": "string" } } }, "ProofingStatusRejectedRejectionMaxProvisioningsReached": { "description": "An object indicating a max provisionings reached rejection.", "type": "object", "properties": { "maxNumberOfProvisioningsAllowed": { "description": "The max number of provisionings allowed, as set by the issuer's policy.", "type": "integer", "format": "int32" } } }, "ProofingStatusRejectedRejectionRiskCheckFailure": { "description": "An object indicating a risk check failure rejection. This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "ProofingStatusRejectedRejectionLivenessCheckFailure": { "description": "An object indicating a liveness check failure rejection. This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "ProofingStatusChallenged": { "description": "An object representing a challenged proofing status.", "type": "object", "properties": { "challengeDescription": { "description": "A description of the challenge for support reps to debug. Note that this is never shown to users. It can contain descriptive, non-sensitive text used for debugging. Warning: Do not include any PII in this message.", "type": "string" }, "physicalLocationVisit": { "description": "A challenge where a user must visit a physical location, such as an issuer's office, to complete a challenge.", "$ref": "#/definitions/ProofingStatusChallengedPhysicalLocationVisit" }, "issuerUrlVisit": { "description": "A challenge option where a user must visit a URL provided by the issuer, and complete a challenge at that URL.", "$ref": "#/definitions/ProofingStatusChallengedIssuerUrlVisit" }, "additionalTimeRequired": { "description": "A challenge option where some more time is needed for reviewing this proofing.", "$ref": "#/definitions/ProofingStatusChallengedAdditionalTimeRequired" } } }, "ProofingStatusChallengedPhysicalLocationVisit": { "description": "An object representing the challenge option where a user must visit a physical location, such as an issuer's office, to complete a challenge. This challenge is out of band of Google. For security reasons, if the issuer is supporting this challenge type, they must provide the location details to Google during onboarding.", "type": "object", "properties": { } }, "ProofingStatusChallengedIssuerUrlVisit": { "description": "An object representing the challenge option where a user must visit a URL provided by the issuer, and complete a challenge at that URL. This challenge is out of band of Google. For security reasons, if the issuer is supporting this challenge type, they must provide the URL to Google during onboarding.", "type": "object", "properties": { } }, "ProofingStatusChallengedAdditionalTimeRequired": { "description": "An object representing the challenge option where addition time is required to review the proofing. The estimated completion time can optionally be provided.", "type": "object", "properties": { "estimatedCompletion": { "description": "The estimated time at which the proofing will be completed. the review if available. The format is a timestamp and the timestamp is represented as the number of milliseconds since the Unix epoch.", "type": "string", "format": "int64" } } }, "ProofingStatusCanceled": { "description": "An object representing a canceled proofing status. This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "ProofingStatusRevoked": { "description": "An object representing a revoked proofing status. This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "ProofingStatusExpired": { "description": "An object representing an expired proofing status. This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "CancelProofingRequest": { "description": "A request to cancel a proofing. This proofing must be in a Pending, Challenged or Cancelled state. If not, an [invalidState](..\/ErrorResponse#InvalidState) ErrorResponse must be returned.", "type": "object", "properties": { "requestMetadata": { "description": "The metadata about the request, required in all requests.", "$ref": "#/definitions/RequestMetadata" }, "deviceReferenceId": { "description": "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.", "type": "string" }, "proofingId": { "description": "An opaque identifier representing a proofing with a specific bundle of evidence, for a specific device. Ex: UUID This proofing must be in a Pending, Challenged or Cancelled state. If not, an [invalidState](..\/ErrorResponse#InvalidState) ErrorResponse must be returned.", "type": "string" } } }, "CancelProofingResponse": { "description": "A response to a request to cancel a proofing.", "type": "object", "properties": { "responseMetadata": { "description": "The metadata about the response, required in all responses.", "$ref": "#/definitions/ResponseMetadata" } } }, "ProvisionCredentialRequest": { "description": "A request to provision a credential.", "type": "object", "properties": { "requestMetadata": { "description": "The metadata about the request, required in all requests.", "$ref": "#/definitions/RequestMetadata" }, "deviceReferenceId": { "description": "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.", "type": "string" }, "credentialId": { "description": "An opaque identifier representing a specific credential provisioned to a device. If the credential_id already exists, instead of creating a new credential, this method should return the existing credential. Ex: UUID", "type": "string" }, "proofingId": { "description": "An opaque identifier representing a proofing with a specific bundle of evidence, for a specific device. The proofing must be in an Approved state. If not, an invalid identifier ErrorResponse should be returned.", "type": "string" }, "deviceEncryptionKey": { "description": "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.", "$ref": "#/definitions/DeviceEncryptionKey" } } }, "DeviceEncryptionKey": { "description": "An ephemeral encryption public key, and associated metadata.", "type": "object", "properties": { "publicKey": { "description": "The base64 encoded ephemeral public key, generated by the device for this request. The key is Elliptic Curve Point in Uncompressed format, as specified by the HPKE KEM-encoding.", "type": "string" }, "signature": { "description": "The base64 encoded signature of the ephemeral public key, signed by the device's identity key. This will be a COSE_Sign1 object, in the ProofOfOwnership format. The \"challenge\" in this format will be SHA-256(ephemeral public key).", "type": "string" }, "keyId": { "description": "The key id of the ephemeral public key generated by the device.", "type": "string" } } }, "ProvisionCredentialResponse": { "description": "A response containing the provisioned credential.", "type": "object", "properties": { "responseMetadata": { "description": "The metadata about the response, required in all responses.", "$ref": "#/definitions/ResponseMetadata" }, "credential": { "description": "The provisioned credential.", "$ref": "#/definitions/Credential" }, "credentialVersionId": { "description": "The current version of the credential that has been provisioned.", "type": "string" } } }, "Credential": { "description": "The mdoc based Credential, as defined by the relevant ISO standard for the credential type. For example, for a mobile drivers license, this would be ISO\/IEC 18013-5. See [this](https:\/\/developers.google.com\/wallet\/identity\/provisioning\/api-reference\/encrypted-object-formats#credential) for mDL mDoc format.", "type": "object", "properties": { "encryptedData": { "description": "The encrypted value and encryption metadata necessary to decrypt the value.", "$ref": "#/definitions/EncryptedData" }, "unencryptedValue": { "description": "The base64 encoded value of the credential.", "type": "string" } } }, "ProvisionMobileSecurityObjectsRequest": { "description": "A request to provision mobile security objects.", "type": "object", "properties": { "requestMetadata": { "description": "The metadata about the request, required in all requests.", "$ref": "#/definitions/RequestMetadata" }, "deviceReferenceId": { "description": "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.", "type": "string" }, "credentialId": { "description": "An opaque identifier representing a specific credential provisioned to a device. Ex: UUID", "type": "string" }, "authKeys": { "description": "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.", "type": "array", "items": { "$ref": "#/definitions/AuthKey" } }, "proofOfProvisioning": { "description": "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.", "$ref": "#/definitions/ProofOfProvisioning" }, "deviceEncryptionKey": { "description": "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.", "$ref": "#/definitions/DeviceEncryptionKey" }, "credentialVersionId": { "description": "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.", "type": "string" } } }, "AuthKey": { "description": "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()", "type": "object", "properties": { "encryptedData": { "description": "The encrypted value and encryption metadata necessary to decrypt the value.", "$ref": "#/definitions/EncryptedData" }, "unencryptedValue": { "description": "The base64 encoded value of the AuthKey.", "type": "string" } } }, "ProofOfProvisioning": { "description": "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)", "type": "object", "properties": { "encryptedData": { "description": "The encrypted value and encryption metadata necessary to decrypt the value.", "$ref": "#/definitions/EncryptedData" }, "unencryptedValue": { "description": "The base64 encoded value of the ProofOfProvisioning.", "type": "string" } } }, "ProvisionMobileSecurityObjectsResponse": { "description": "A response containing the result of provisioning mobile security objects.", "type": "object", "properties": { "responseMetadata": { "description": "The metadata about the response, required in all responses.", "$ref": "#/definitions/ResponseMetadata" }, "mobileSecurityObjects": { "description": "A list of MobileSecurityObjects that are ready. This list may be empty if no MobileSecurityObjects are currently ready.", "type": "array", "items": { "$ref": "#/definitions/MobileSecurityObject" } } } }, "MobileSecurityObject": { "description": "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.](https:\/\/developers.google.com\/wallet\/identity\/provisioning\/api-reference\/encrypted-object-formats#static_auth_data)", "type": "object", "properties": { "encryptedData": { "description": "The encrypted value and encryption metadata necessary to decrypt the value.", "$ref": "#/definitions/EncryptedData" }, "unencryptedValue": { "description": "The base64 encoded value of the credential.", "type": "string" }, "expirationTimeMillis": { "description": "A timestamp representing when the mobile security object expires. The timestamp is represented as the number of milliseconds since the Unix epoch.", "type": "string", "format": "int64" } } }, "GetCredentialStatusRequest": { "description": "A request to retrieve the current status of a credential.", "type": "object", "properties": { "requestMetadata": { "description": "The metadata about the request, required in all requests.", "$ref": "#/definitions/RequestMetadata" }, "deviceReferenceId": { "description": "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.", "type": "string" }, "credentialId": { "description": "The id of the credential that the caller is requesting the status of.", "type": "string" } } }, "GetCredentialStatusResponse": { "description": "A response containing the current status of a credential.", "type": "object", "properties": { "responseMetadata": { "description": "The metadata about the response, required in all responses.", "$ref": "#/definitions/ResponseMetadata" }, "credentialStatus": { "description": "The current status of the credential.", "$ref": "#/definitions/CredentialStatus" }, "credentialVersionId": { "description": "The current version of the credential. This is expected to change when new versions of the credential become available. An example of when this would change is when the user updates their address on their credential, making the underlying mdoc stale.", "type": "string" } } }, "CredentialStatus": { "description": "An object representing the different statuses a credential can have.", "type": "object", "properties": { "provisionPending": { "description": "Represents a credential that can be retrieved, but has not yet provided ProofOfProvisioning. Any calls to ProvisionMobileSecurityObjects for a credential in this state should fail if the request doesn't contain an updated ProofOfProvisioning. A credential is put into this state when it is created, and when there is a new version of a credential available. For the new version case, the wallet must re-provision the credential and provide ProofOfProvisioning to go back to an ACTIVE state.", "$ref": "#/definitions/CredentialStatusProvisionPending" }, "active": { "description": "Represents an active and usable credential. MSOs can only be retrieved for a credential in the ACTIVE state.", "$ref": "#/definitions/CredentialStatusActive" }, "revoked": { "description": "Represents a credential that is in a final, un-usable state. This credential can not become usable in the future. This state is comparable to DELETED, but can only be set by the issuer.", "$ref": "#/definitions/CredentialStatusRevoked" }, "deleted": { "description": "Represents a credential that was once provisioned, but has been deleted from the device. This state is comparable to REVOKED, but can only be set by the wallet.", "$ref": "#/definitions/CredentialStatusDeleted" }, "userActionRequired": { "description": "Action required by the user to avoid their credential moving to a more restricted state (e.g. ACTIVE -> REVOKED).", "$ref": "#/definitions/CredentialStatusUserActionRequired" } } }, "CredentialStatusProvisionPending": { "description": "An object representing a provision pending credential status. This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "CredentialStatusActive": { "description": "An object representing an active credential status. This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "CredentialStatusRevoked": { "description": "An object representing a revoked credential status. This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "CredentialStatusDeleted": { "description": "An object representing a deleted credential status. This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "CredentialStatusUserActionRequired": { "description": "An object representing a task \/ action that the user needs to complete.", "type": "object", "properties": { "deadlineTimeMillis": { "description": "The epoch time of when when the action expires and the issuer is expected to move the credential to a more restricted state. Used by the client to warn the user about when the action needs to be completed by but it is up to the issuer to enforce restrictions.", "type": "string", "format": "int64" }, "deadlineEnforcementHint": { "description": "Hint describing how the issuer would enforce the deadline of the action.", "$ref": "#/definitions/CredentialStatusUserActionRequiredEnforcementHint" }, "submitProofing": { "description": "Submit proofing of the credential.", "$ref": "#/definitions/CredentialStatusUserActionRequiredSubmitProofing" } } }, "CredentialStatusUserActionRequiredEnforcementHint": { "description": "Hint describing how the issuer would enforce the action required.", "type": "object", "properties": { "revocationHint": { "description": "Credential will be revoked by the issuer.", "$ref": "#/definitions/CredentialStatusUserActionRequiredEnforcementHintRevocationHint" } } }, "CredentialStatusUserActionRequiredEnforcementHintRevocationHint": { "description": "Credential will be revoked by the issuer.", "type": "object", "properties": { } }, "CredentialStatusUserActionRequiredSubmitProofing": { "description": "Details of the proofing status.", "type": "object", "properties": { "limitedAttempts": { "description": "The user has limited attempts to submit proofing.", "$ref": "#/definitions/CredentialStatusUserActionRequiredSubmitProofingLimitedAttempts" }, "unlimitedAttempts": { "description": "The user has unlimited attempts to submit proofing. This is not recommended to the issuer.", "$ref": "#/definitions/CredentialStatusUserActionRequiredSubmitProofingUnlimitedAttempts" } } }, "CredentialStatusUserActionRequiredSubmitProofingLimitedAttempts": { "description": "The user has limited attempts to submit proofing.", "type": "object", "properties": { "remainingAttempts": { "description": "The number of remaining attempts to submit proofing. This is only for UX message diplay. Google Wallet will not act on this number.", "type": "integer", "format": "int32" }, "maxAttempts": { "description": "The maximum number of attempts to submit proofing. This is only for UX message diplay. Google Wallet will not act on this number.", "type": "integer", "format": "int32" }, "maxAttemptsEnforcementHint": { "description": "Hint describing how the issuer would enforce the max attempts.", "$ref": "#/definitions/CredentialStatusUserActionRequiredEnforcementHint" } } }, "CredentialStatusUserActionRequiredSubmitProofingUnlimitedAttempts": { "description": "The user has unlimited attempts to submit proofing. This is not recommended to the issuer.", "type": "object", "properties": { } }, "NotifyCredentialDeletedRequest": { "description": "A request to notify an issuer that a credential was deleted.", "type": "object", "properties": { "requestMetadata": { "description": "The metadata about the request, required in all requests.", "$ref": "#/definitions/RequestMetadata" }, "deviceReferenceId": { "description": "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.", "type": "string" }, "credentialId": { "description": "The id of the credential that the wallet has deleted.", "type": "string" } } }, "NotifyCredentialDeletedResponse": { "description": "A response acknowledging the deletion of a credential.", "type": "object", "properties": { "responseMetadata": { "description": "The metadata about the response, required in all responses.", "$ref": "#/definitions/ResponseMetadata" } } }, "GetDeviceRegistrationNonceRequest": { "description": "A request to get a device registration nonce.", "type": "object", "properties": { "requestMetadata": { "description": "The metadata about the request, required in all requests.", "$ref": "#/definitions/RequestMetadata" }, "deviceReferenceId": { "description": "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.", "type": "string" } } }, "GetDeviceRegistrationNonceResponse": { "description": "A response containing the device registration nonce.", "type": "object", "properties": { "responseMetadata": { "description": "The metadata about the response, required in all responses.", "$ref": "#/definitions/ResponseMetadata" }, "nonce": { "description": "The nonce to be used for device registration. This must be a maximum of 32 bytes, due to a restriction in the Android IdentityCredential library.", "type": "string" } } }, "RegisterDeviceRequest": { "description": "A request to get a register a device.", "type": "object", "properties": { "requestMetadata": { "description": "The metadata about the request, required in all requests.", "$ref": "#/definitions/RequestMetadata" }, "deviceReferenceId": { "description": "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.", "type": "string" }, "deviceIdentityCertificate": { "description": "(DEPRECATED: use deviceIdentityCertificateChain ) An X.509 certificate chain, that is unique for a specific device and credential. This certificate contains the device's identity key, a device attestation, and the signed nonce.", "type": "string" }, "deviceIdentityCertificateChain": { "description": "A list of X.509 certificates in the certificate chain, that is unique for a specific device and credential. This certificate chain contains the device's identity key, a device attestation, and the signed nonce.", "type": "array", "items": { "type": "string" } } } }, "RegisterDeviceResponse": { "description": "A response acknowledging the device registration.", "type": "object", "properties": { "responseMetadata": { "description": "The metadata about the response, required in all responses.", "$ref": "#/definitions/ResponseMetadata" } } }, "GetIdentityKeyRequest": { "description": "A request to retrieve the issuer's identity key for use in end to end encryption.", "type": "object", "properties": { } }, "GetIdentityKeyResponse": { "description": "A response containing one or more of the issuer's active identity keys.", "type": "object", "properties": { "issuerIdentityCertificate": { "description": "A list of identity keys that are active for an issuer. At least 2 identity keys are required during key rotation. After rotation is complete, only the active key should be sent. Each entry should be base64 encoded DER format X.509 certificate containing the identity key.", "type": "array", "items": { "type": "string" } } } }, "GetHybridEncryptionKeyRequest": { "description": "A request to retrieve the issuer's public encryption key for use in end to end encryption.", "type": "object", "properties": { } }, "GetHybridEncryptionKeyResponse": { "description": "A response containing the issuer's active public encryption key.", "type": "object", "properties": { "issuerEncryptionCertificate": { "description": "The active encryption key for an issuer, to be used for end to end encryption. This is formatted as a base64 encoded DER format X.509 certificate containing the encryption key.", "type": "string" } } }, "ErrorResponse": { "description": "ErrorResponse object for all methods. This is returned instead of the usual response type, when there is an error. This object should not be used for business logic based rejections.", "type": "object", "properties": { "responseMetadata": { "description": "The metadata about the response, required in all responses.", "$ref": "#/definitions/ResponseMetadata" }, "errorDescription": { "description": "Provide a description of this status for support reps to debug errors. Note that this is never shown to users. It can contain descriptive, non-sensitive text used for debugging. Note that some values for errorResponseCode should be accompanied by additional detail in this field. Warning: Do not include any PII in this message.", "type": "string" }, "issuerErrorIdentifier": { "description": "This identifier is specific to the issuer and is generated by the issuer. It is used for debugging purposes only in order to identify this error. This is the identifier that the issuer knows this error by.", "type": "string" }, "invalidApiVersion": { "description": "Used if the request's API version is unsupported. Advised HTTP Code: 400", "$ref": "#/definitions/ErrorResponseInvalidApiVersion" }, "invalidPayloadSignature": { "description": "Used if the signature of the payload is to an unknown or inactive key. Advised HTTP Code: 401", "$ref": "#/definitions/ErrorResponseInvalidPayloadSignature" }, "invalidPayloadEncryption": { "description": "Used if the encryption of the payload is to an unknown or inactive key. Advised HTTP Code: 400", "$ref": "#/definitions/ErrorResponseInvalidPayloadEncryption" }, "invalidIdentifier": { "description": "Used if an identifier sent in the request was invalid or unknown. Advised HTTP Code: 404", "$ref": "#/definitions/ErrorResponseInvalidIdentifier" }, "invalidFieldValue": { "description": "Used if the request contains a value for a field that isn't in the set of supported values. Advised HTTP Code: 400", "$ref": "#/definitions/ErrorResponseInvalidFieldValue" }, "missingRequiredField": { "description": "Used if a field that is required is unset in the request. Advised HTTP Code: 400", "$ref": "#/definitions/ErrorResponseMissingRequiredField" }, "invalidDecryptedRequest": { "description": "Used if the request payload could be decrypted, but the resulting message could not be parsed. Advised HTTP Code: 400", "$ref": "#/definitions/ErrorResponseInvalidDecryptedRequest" }, "permissionDenied": { "description": "Used if the request was declined due to issues related to any permission credentials that Google sends in the API calls. Advised HTTP Code: 403", "$ref": "#/definitions/ErrorResponsePermissionDenied" }, "forbidden": { "description": "Access to the requested resource is forbidden. Advised Http Code: 403", "$ref": "#/definitions/ErrorResponseForbidden" }, "invalidState": { "description": "Used if a request was made, but the system is not in a valid state to perform the request. Ex: ProvisionCredential is called with a Rejected proofing. Advised HTTP Code: 400", "$ref": "#/definitions/ErrorResponseInvalidState" } } }, "ErrorResponseInvalidApiVersion": { "description": "Object containing information about an invalid API version error.", "type": "object", "properties": { "requestVersion": { "description": "The invalid version that was specified on the request.", "$ref": "#/definitions/Version" }, "expectedVersion": { "description": "The expected version.", "$ref": "#/definitions/Version" } } }, "ErrorResponseInvalidPayloadSignature": { "description": "This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "ErrorResponseInvalidPayloadEncryption": { "description": "This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "ErrorResponseInvalidIdentifier": { "description": "Object containing information about an invalid identifier error.", "type": "object", "properties": { "invalidIdentifierType": { "description": "The type of identifier that was invalid, e.g. proofing id, document id, etc.", "type": "string" } } }, "ErrorResponseInvalidFieldValue": { "description": "Object containing information about an invalid field value error.", "type": "object", "properties": { "invalidFieldName": { "description": "The name of the field that was found to be invalid.", "type": "string" } } }, "ErrorResponseMissingRequiredField": { "description": "Object containing information about an missing required field error.", "type": "object", "properties": { "missingFieldNames": { "description": "The names of the missing fields.", "type": "array", "items": { "type": "string" } } } }, "ErrorResponseInvalidDecryptedRequest": { "description": "This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "ErrorResponsePermissionDenied": { "description": "Object containing information about a permission denied error.", "type": "object", "properties": { "reason": { "description": "The reason for denying the permission.", "type": "string" } } }, "ErrorResponseForbidden": { "description": "This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } }, "ErrorResponseInvalidState": { "description": "This message is intentionally empty right now. New fields could be added in the future.", "type": "object", "properties": { } } } }