Web Auth API

If you want to authorize a user in your service by means of his Waves.Exchange account, here's the solution. You can redirect the user to the official Waves.Exchange app (https://waves.exchange) with certain query parameters including some arbitrary data for the user to sign.

That might be needed in cases when you work with user personal data and to be sure that a given blockchain account belongs to that user.

Process

1. You add the Waves.Exchange Auth widget to your site.
2. A user stumbles upon your site and wants to log in using his Waves.Exchange account.
3. The user clicks the widget button and gets redirected to the official Waves.Exchange app, along with some data from the widget.
4. There, the user chooses whether to log in or cancel that chain of actions.
5. If the user proceeds, the data will be signed with the user's private key.
6. The user then gets redirected back to your site, along with the signature and user's public key.
7. You check the validity of the signature against the data provided for the user.
8. If everything is correct, the user is now authenticated in your service.

If the user interrupts the process, he stays on the Waves.Exchange app page.

Details

Due to the length limitations of the query string all parameters are expressed with one character.

Request

Example

https://waves.exchange#gateway/auth?r=https://example.com&n=ServiceName&d=0123456789abc&i=/img/logo.png&success=/wavesAuth

Basic path is https://waves.exchange#gateway/auth. Then the query parameters go.

Referrer

r=https://example.com — the URL of your service. It should be HTTPS-only. (Required)

Name

n=Service%20Name — the name of your service. (Required)

Data

d=randomChars — the data which is signed by the user's private key. (Required)

Icon path

i=/path/to/the/icon.png — a path relative to the Referrer parameter. It hosts the logo of your app. (Optional)

Success path

s=/path/to/an/API/method — a path to the method which redirects the user while the signing is successful. By default, the user is redirected to the referrer root. (Optional)

Debug mode

debug=true — a flag to display error messages. (Optional)

Response

Example

https://example.com/?s=2w7QKSkxKEUwCVhx2VGrt5YiYVtAdoBZ8KQcxuNjGfN6n4fi1bn7PfPTnmdygZ6d87WhSXF1B9hW2pSmP7HucVbh&p=2M25DqL2W4rGFLCFadgATboS8EPqyWAN3DjH12AH5Kdr&a=3PCAB4sHXgvtu5NPoen6EXR5yaNbvsEA8Fj

Signature

s=base58EncodedSignature — a signature of the data which is signed by the user's private key.

Public key

p=base58EncodedPublicKey — user's public key.

Address

a=base58EncodedAddress — user's Waves.Exchange address.

How to check signature validity

Signed data consists of three objects Prefix string + URL host + Provided Data. Signature is taken from the data in the following order: a WavesWalletAuthentication string, then a string with your host parameter value, then a string with your data parameter value. All strings are converted to length bytes + value bytes as in Data Transactions. Prefix string and the host is required for security purposes if malicious service tries to use transaction data and signature from Auth API it would be useless to broadcast into blockchain.

We also suggest address validation in case the signature and public key is valid but the address was swapped.

See code examples in the Waves Keeper API article of the Waves protocol documentation.