# 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 (opens new window)) 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 want to be sure that a given blockchain account belongs to that user.

# Process

You add to your site the link as follows:
```
https://waves.exchange#gateway/auth?r=https://example.com&n=ServiceName&d=0123456789abc&i=/img/logo.png&s=/wavesAuth.
```
where:

r=https://example.com - URL of your service.

n=ServiceName - name of your service.

d=0123456789abc - data signed with user's private key.

i=/img/logo.png - path to the logo of your service.

s=/wavesAuth - path to the method that redirects the user when the signature is successful.
The user opens the link and gets redirected to the official Waves.Exchange app to login the system.
After logging in the user provides to your site the access to the address and the data is signed with the user's private key.
The user then gets redirected back to your site, along with the signature and user's public key.
You check the validity of the signature against the data provided for the user.
If everything is correct, the user is now authenticated in your service.

# 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&s=/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 (opens new window) article of the Waves protocol documentation.