Verification and Issue 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).
After scan the QrCode a flow of connection (5) between the wallet and the DARS will start
on "backgroud". If is the first time that the walle connect with the DARS a connection notify callback (6) will be send to the customer backend.
If the wallet was previously connected to the customer the connection will be reused.
After the connection, theThe wallet will show the proof requested to the user. After the user accept to send the data a flow of credential verification will start (7)5) on "background".
IfEvent credentialsstatus areof validprogression aof verify/confirmthe callback (8)verification will be sendsent to the customeCustomer backend.
via callback api "verify/event" (6).
With the verify/confirmevent 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.
IF the data are valid for the own customare service of issuing a subsequent credential a credential/offer (8) API to create a credential offer, the credential_offer_link resultat (9) andwill addbe embendeed into the verify/update payload.
Customer will sent a verify/update to the response
this result"COMPLETE" (10) 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.user Optionallywallet.
The addwallet awill genericreceive responseinformation about the result andfor waitthis to futher check or business logiverification (11) toand sendwill aevaluate verify/the response (12)(13).
ToBy retreiving the credential_offer_link the wallet will start the issue phase (14)
At the end of the issue phase an credential/offer/event callback (15) will be send a text comunication to the usercustome walletbackend a notify/send (13) api can be used and a new push notification will be sent towith the walletstatus (14).
Atfor this point, if the customer want to send one or more credential can sent a credential offer to the wallet by using the credentila/offer (15) Api and a new notification with this offer will be received to the wallet.
If the user/wallet accept the offer a issuing flow (16) will start in "background".
In the issuing will be completed with success a confirm_issue callback (17) will be sent to the customer backend.event.
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 Studio.
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/response With this service an organization can confirm or reject a verification. 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 or reject the verification. The same Api can be used to “update” the notification status of an existing proof notification .
POST /verify/response
Request body:
{
"presentation_id": "string",
"result": true,
"descriptions": [
{
"lang": "string",
"message": "string"
}
]
"verify_result": string", (optional)
}
presentation_id : is a unique identifier for a specific outcome of a verification. This value will be received through the confirm verify callback.
result :
true - if the organization confirms a successful verification for credential
Example for notification status in wallet
false - if the organization refuse/reject credential data
Example for notification status in wallet
verify_result
IN_PROGRESS - 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
agent/notify/send With this service an organization can send a push notification to the user wallet. In this case can send a message with the queue_item_id
POST /agent/notify/send
Request body:
{
"connection_id": "d36b5123-27a3-45db-a5c1-ba696b42880a",
"mime-type": "text/html",
"title": [
{
"lang": "it",
"message": "string"
},
{
"lang": "en",
"message": "string"
}
],
"body": [
{
"lang": "it",
"message": "base64 string"
},
{
"lang": "en",
"message": "base64 string"
}
]
}
connection_id : is a unique identifier for a specific connection with a user wallet. This value will be received through the connection notify callback.
mime-type : text/html for html body message. text/plain for plain text message
title : list of message title in various language
body : list of body title in various language
Example Response body:
{
"status_code": 0,
"message_code": 0,
"message": "string",
"notify_id": "string"
}
status_code : 100 success, 101 failure
message_code : internal message code for operation
message : label for message of the operation
notify_id : is a unique identifier for a specific notification.
credential/offer
The service allows to create a credential offer. The offer can be sent through a pairwise connection (using connection_id).
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