Verification Integration Flow
Sequence
Call verify/request (1) API to create a new proof verification, the invitiation_short_url resultat (2) can be embendeed in a QrCode (3) that can be scan from the user with the Dizme Wallet app (4).
The wallet will show the proof requested to the user. After the user accept to send the data a flow of credential verification will start (5) on "background". Event status of progression of the verification will be sent to the Customer Backend via callback api "verify/event" (6). With the verify/event the customer backend will receive also the data sent from the wallet.
At this point (7) on the backend can be done right away a check on the data received.
Customer will sent a verify/update to "COMPLETE" (8) the verification adding also information about the own check on the data received. Optionally can be added an info message to be shown to the user wallet.
The wallet will receive information about the result for this verification (9) and will evaluate the response (10).
DARS Api
verify/request
The /verify/request service allows you to ask for verifiable credentials to a user
In order to request verifiable credentials to a user, a proof template (or request) must be previously created for the own organization. The proof request can be configured using Dizme Studio (see documentation)
POST /verify/request
Request body:
{
"business_code": "string",
"allow_multiple_read": true,
"request_uid": "string"
}
busines_code : business code of the proof template configured on Dizme Stack.
By example PROOF_01 business code
allow_multiple_read : true value consent to scan many time the same qrcode from several users
request_uid : must be set with an own generated unique identifier for the request, if the attribute is omitted, a unique identifier will be automatically generated
Example Response body:
{
"status_code": 100,
"message_code": 400,
"message": "Invitation Created!",
"request_uid": "12345-12345-12345",
"invitation_short_link": "https://agent.dizme.io/api/v1/invitation/12345-12345-12345"
}
status_code : 100 success, 101 failure
message_code : internal code for operation 400 for “Invitation Created”
message : label for message of the operation
request_uid : the unique identifier of the request already sent or generated by the system.
invitation_short_link: url to be embended into ar qrcode/or to send to the user via other method (sms, email, webpage)
verify/update With this service an organization can complete a verification activity optionally adding the check result on the data received. Usually after a confirm verify with a success response an organization makes some business logic check or operation. Based on the result of this operation the organization can decide to confirm the success of the verification or the verification. Optionally can added a info message to be shown to the user or a subsequent credential offer link
POST /verify/update
Request body:
{
"presentation_id": "string",
"status": true, /* COMPLETED - NEED_CHECK - CHECK_FAIL */
"messages": [
{
"lang": "string",
"body": "string"
"title": "string
},
],
"availableActions":[
{
"action":"ISSUE"
"data": {
"credential_offer_link" : "...."
}
}
]
}
presentation_id : is a unique identifier for a specific outcome of a verification. This value will be received through the verify/event callback.
status :
COMPLETED - if the organization confirms a successful verification for credential
Example for notification status in wallet
CHECK_FAIL - if the organization refuse/reject credential data
Example for notification status in wallet
WAITING_CONFIRM - in combination with result=true can be used to define an in progress verification after received data credential.
Usually is used false when the organization accept the data from the proof response and need some other async operation to complete the verification
descriptions : list of messages description in various language
Example Response body:
{
"status_code": 100,
"message_code": 400,
"message": "Invitation Created!"
}
status_code : 100 success, 101 failure
message_code : internal message code for operation
message : label for message of the operation
credential/offer
The service allows to create a credential offer. The offer can be sent through a pairwise connection (using connection_id).
```bash
POST /credential/offer
Request body for Certified Credential:
{
"request_uid": "string",
"connection_id": "string",
"credential_def_id": "string",
"credential_values": [
{
"name": "string",
"mime_type": "string",
"value": "string"
}
],
"comment": "string"
}
Example for credential values :
Certified identity
"credential_values": [
{
"mime_type": "text/plain",
"name": "name",
"value": "MARIO"
},
{
"mime_type": "text/plain",
"name": "surname",
"value": "ROSSI"
},
{
"mime_type": "text/plain",
"name": "birthdate",
"value": "30-10-1960"
},
{
"mime_type": "text/plain",
"name": "birthplace",
"value": "ROMA"
},
{
"mime_type": "text/plain",
"name": "citizenship",
"value": "ITA"
},
{
"mime_type": "text/plain",
"name": "credentialIssueTimestamp",
"value": "1633970952"
}
]
request_uid : must be set with an own generated unique identifier for the request, if the attribute is omitted, a unique identifier will be automatically generated
connection_id : is a unique identifier for a specific connection with a user wallet. This value will be received through the connection notify callback.
credential_def_id : is the unique identifier of the credential that the organization wants to issue.
For all the credential_values requested you need to check the attributes of the specific credential.
You can found this information on Dizme Studio or on the Sovrin block chain
Example Response body:
{
"status_code": 0,
"message_code": 0,
"message": "string",
"request_uid": "string"
}
status_code : 100 success, 101 failure
message_code : internal message code for operation
message : label for message of the operation
request_uid : the unique identifier of the request already sent or generated by the system.
Callback API
connection/notify The organization will receive this callback after a pairwise connection (previously requested) has been established. Note that in case of verify request or credential offer without connection, a pairwise connection is established before the verify or issue operation. This service is invoked even if a connection has been reused by the owner.
POST /owners/connection/notify
Request body:
{
"connection_id": "string",
"status": "string",
"request_uid": "string",
"reused": true
}
connection_id : is a unique identifier for a specific connection with an user wallet. This value will be received through the connection notify callback.
reused : true value if is an existent connection with user
status : “active”
request_uid :
is a unique identifier of the request that triggered the connection (verify request, credential offer, connection offer)
Example Response body:
{
"status_code": "100",
"message_code": "0",
"message": "Success!"
}
status_code : 100 success, 101 failure
message_code : internal code for operation 400 for “Invitation Created”
message : label for message of the operation
verify/confirm Upon invocation of this service, all the attributes requested in the verify request will be received.
POST/verification/verify/confirm
Request body:
{
"organization_name": "string",
"proof_business_code": "string",
"request_uid": "string",
"revealed_attributes": {},
"unrevealed_attributes": {},
"self_attested_attributes": {},
"proof_request": {},
"proof": {},
"presentation_id": "string",
"connection_id": "string"
}
example of revealed attribute :
revealed_attributes : {“attribute1”:”value”, “attribute2”:”value}
proof_business_code : business code of the proof template configured.
By example PROOF_01 is configured
request_uid :
is a unique identifier of the verify request
organization_name : name of the organization that require the proof
proof_request : raw value of the proof request
proof : raw value of the proof sent by the user wallet
presentation_id : is a unique identifier for a specific outcome of a verification.
revealed_attributes : all the attributes that comes from credential with the value revealed
self_attested_attributes : all the attributes that comes from self attested
unrevealed_attributes : all the attributes that comes from credential but without the value
Example Response body:
{
"status_code": 100,
"message_code": 0,
"message": "Success!",
"result": true,
"send_response": false,
"descriptions": [
{
"lang": "en",
"message": "Verifica eseguita con successo"
},
{
"lang": "it",
"message": "Verify executed successfully"
}
]
}
status_code : 100 success, 101 failure
message_code : internal code for operation 400 for “Invitation Created”
message : label for message of the operation
result : result of the organization verification. The organization accept the data of the proof response
send_response :
true - send the response status to the wallet user
result=true - if the organization confirms a successful verification for credential
result=false - if the organization refuse/reject credential data
false - don’t send the response to the wallet . Usually is used false when the organization accept the data from the proof response and need some other async operation to complete the verification
descriptions: text messages
confirm/issue
Send the confirm for an issued credential
POST /owners/credential/confirm_issue
Request body:
{
"connection_id": "string",
"request_uid": "string",
"credential_def_id": "string",
"tid": "string",
"credential_exchange_id": "string"
}
connection_id : is a unique identifier for a specific connection with an user wallet. This value will be received through the connection notify callback.
credential_def_id : id of the credential issued
tid : transaction id of the issue
credential_exchange_id : is a unique identifier for a specific exchange of credentials.
request_uid :
is a unique identifier of the request that triggered the connection (verify request, credential offer, connection offer)
Example Response body:
{
"status_code": "100",
"message_code": "0",
"message": "Success!"
}
status_code : 100 success, 101 failure
message_code : internal code for operation 400 for “Invitation Created”
message : label for message of the operation
proof/discard
Forwarded the proof discard sent by the wallet owner
POST owners/proof/discard
Request body:
{
"connection_id": "string",
"request_uid": "string",
"description": "string"
}
connection_id : is a unique identifier for a specific connection with an user wallet. This value will be received through the connection notify callback.
request_uid :
is a unique identifier of the request that triggered the verification
description : description added from the wallet owner when reject the proof
Example Response body:
{
"status_code": "100",
"message_code": "0",
"message": "Success!"
}
status_code : 100 success, 101 failure
message_code : internal code for operation 400 for “Invitation Created”
message : label for message of the operation
credential/discard
Forwarded the credential offer discard sent by the wallet owner. When a user receives a credential offer notification, can decide to refuse/reject the credential offered for some reason. By the rejection the organization receive this callback back to be informed about the user choice
POST owners/credential/discard
Request body:
{
"connection_id": "string",
"request_uid": "string",
"credential_def_id": "string",
"description": "string"
}
connection_id : is a unique identifier for a specific connection with an user wallet. This value will be received through the connection notify callback.
request_uid :
is a unique identifier of the request that triggered the credential offer
credential_def_id : id of the credential rejected
description : description added from the wallet owner when reject the credential
Example Response body:
{
"status_code": "100",
"message_code": "0",
"message": "Success!"
}
status_code : 100 success, 101 failure
message_code : internal code for operation 400 for “Invitation Created”
message : label for message of the operation