Quelltext der Seite RESTAPI:About Verifications

= Verifications =
Most of the services offered by the Cryptshare Server require a form of verification, before they can be used. The Cryptshare Server supports two types of verification: '''Email based verification''' and '''Client id based verification'''.

With both verification methods, the REST API consumer receives a '''Verification Token'''. This Verification Token is '''only valid in combination with the email address and the client id''' that were provided during the request of the Verification Token.

For endpoints that require a verified email address, the Verification Token has to be sent as '''X-CS-VerificationToken''' header.

* Using the '''email based verification''', a verification has to be performed for each sender email address. This makes sure that the sender address that is being used for a transfer through the REST API is valid and authorized for use by its owner. That's important, because the Cryptshare Policy set up on the server grants usage permissions and settings based on the email addresses used for a transfer. To verify a specific sender email address, you need to send a verification request for that email address to the Cryptshare Server. The Cryptshare Server will then send a verification email containing a verification code to the specified sender email address. This verification code will then need to be sent to the Cryptshare server via the REST API to prove that the request was authorized by the email address owner. When the verification code is correct, a verification token is assigned to the REST API consumer that now can be used for the different services. This verification token is only valid for the respective email address and client id. We recommend the email based verification approach for all purposes where users want to perform actions for themselves and have access to their own email inbox, especially for '''web applications'''.

* With '''Client id based verification''', any sender email address can be used for the services, without having to perform an email based verification process. For this, a '''client id''' has to be '''registered in the Cryptshare administration interface'''. After registering the REST API consumer can request a verification token for a specific email address. This verification token is only valid for the respective email address and the requesting client id. The same client id can request verification tokens for different email addresses that only work together as the email address and verification token pair. Please note: Using Client id based verification increases the risk of abuse, since anyone with access to the client id can use the services using any sender email address. It is therefore recommended that Client id based verification only be used if email based verification does not meet your requirements and the client id is not publicly available as in web application calls. Instead, only server-side applications or other applications where REST API calls are not easily visible via the browser's developer tools. Therefore, we recommend the client id based verification only for server applications or trusted environments. Data gained from the server application could be offered to the respective users when custom authentication mechanisms are used.

== Check availability for verification modes ==
GET https://&#x3C;your-url&#x3E;/api/users/&#x3C;email-address>/verification

You can determine which verification methods are available for a client id with the contents of the field '''verificationMethods'''. When the value '''email''' is contained, email based verification is available. When the value '''clientId''' is contained, client id based verification can be used.

== Verification workflows in comparison ==
{| class="wikitable" style="border: 0; text-align: center;"
|+
!Client id based verification
! style="border: 0; border: 0; background-color: white; width: 100px" |
!Email based verification
|-
| colspan="3" style="border: 0; border: 0; background-color: white;" |
|-
|[[RESTAPI:Client id based Verification#Step B: Register client id in Cryptshare administration interface|Use client id that is registered in the Server Backend]]
| rowspan="5" style="border: 0; border: 0; background-color: white;" |
|[[RESTAPI:Basic request headers and client id#Client id|Create a new client id]]
|-
| rowspan="3" style="border: 0; border: 0; background-color: white;" |↓
| style="border: 0; border: 0; background-color: white;" |↓
|-
|[[RESTAPI:Email based Verification#Step 1: Request verification code|Request verification code to user by email]]
|-
| style="border: 0; border: 0; background-color: white;" |↓
|-
|[[RESTAPI:Client id based Verification#Step 1: Request verification token|Create a verification token with the client id]]
|[[RESTAPI:Email based Verification#Step 2: Send verification code and receive verification token|Exchange verification code for a verification token]]
|}

== What is a verified email address? ==
The term '''verified email address''' means that the email address had been verified by requesting a Verification Token via one of the methods above and sending this Verification Token together with the client id and a respective email address inside of the requests to the Cryptshare server. Please note, that a Verification Token is only valid in combination with the client id and email address that were used in the request for the Verification Token itself.

The '''email address''' is usually sent inside the '''request path'''.

The '''Client id''' in the '''X-CS-ClientId''' header.

The '''Verification Token''' in the '''X-CS-VerificationToken''' header.