RESTAPI:Email based Verification

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 (step 1). 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 (step 2). 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.

Preparation: Check availability for email based verification

GET https://<your-url>/api/users/<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.

Step 1: Request verification code

POST https://<your-url>/api/users/<email-address>/verification/code/email

In the Cryptshare Administration Interface, see chapter Verification, administrators are able to configure the maximum number of last issued verification codes for one email address. If this number is exceeded by subsequent requests to this endpoint, the earlier verification codes lose their validity. Verification Codes also have a maximum lifetime that can also be configured in the Cryptshare Administration Interface. As soon as the configured time passed, they cannot be used anymore for receiving a verification token.

To customize the language of the email, the Accept-Language header can be used.

Step 2: Send verification code and receive verification token

POST https://<your-url>/api/users/<email-address>/verification/token

In order to request your verification token, send the verification code inside an JSON object { "verificationCode": "<the verification code from step 1>"} in the request body and set the Content-Type header to application/json.