User Authentication
To get started we require two factors of user-authentication* to receive a JWT token to be passed in the header.
For the purpose of this guide we will use:
- 1.Wallet auth
- 2.SMS auth
Authenticating with a crypto wallet requires two steps
- 1.Retrieve a challenge phrase to be signed with the users wallet.
post
https://api.ratio.me
/v1/auth/cryptoWallet:start
Start a crypto wallet authentication flow
Request
Response
{
"walletAddress": "0x0000000000000000000000000000000000000000",
"walletNetwork": "ETHEREUM"
}
{
"challenge": "Signing in with Ratio: pUQikKqqBq1brTwt1oHhUJwlOTfshzfMEAsJaH7x1MOdN7QMOooFfj-Aujmi7sb0wJnvYqtmZtlszKdH"
}
cURL
curl --location -g --request POST 'https://api.ratio.me/v1/auth/cryptoWallet:start' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"walletAddress": "<WALLET_ADDRESS>",
"walletNetwork": "<ETHEREUM_OR_POLYGON>"
}'
- 2.Then authenticate that signature with the users wallet.
post
https://api.ratio.me
/v1/auth/cryptoWallet:authenticate
Authenticate a user's crypto wallet
Request
Response
{
"walletAddress": "0x0000000000000000000000000000000000000000",
"walletNetwork": "ETHEREUM",
"signature": "2djd2cFZ9VU2zDWvUGqeHwvbiJZfTt3BMzDctDsEW7vM2QUTgTHjeM2rpFX9ZULeic3KptUh5ehipXDFcK5ecYiX"
}
{
"sessionJwt": "eyJhbG.....",
"userMask": {
"id": "00000000-0000-0000-0000-000000000000",
"createTime": "2022-01-01T00:00:00.000Z",
"updateTime": "2022-01-01T23:59:59.999Z",
"phoneMask": "0000",
"preferredMfaMethod": "OTP_SMS"
}
}
cURL
curl --location -g --request POST 'https://api.ratio.me/v1/auth/cryptoWallet:authenticate' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"walletAddress": "<WALLET_ADDRESS>",
"walletNetwork": "<ETHEREUM_OR_POLYGON>",
"signature": "<SIGNED_CHALLENGE_STRING>"
}'
Once a successful authentication takes place, you will receive an authenticated JWT that has to be passed into the authorization header as a bearer token for the subsequent request to ensure they are authenticated to the same session.
First we need to send a one-time code to the user using the phone number they provided in sign up.
post
https://api.ratio.me
/v1/auth/otp/sms:send
Send an SMS OTP to the user
Request
Response
{
"phoneNumber": "+14165551234",
}
{
"phoneId": "phone-number-test-01234abc-0000-0000-0000-0123456789",
"phoneMask": "1234"
}
cURL
curl --location --request POST 'https://api.ratio.me/v1/auth/otp/sms:send' \
--header 'Authorization: Bearer eyJ......' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Content-Type: application/json' \
--data-raw '{
"phoneNumber": "+14165551234"
}'
Once you receive the one-time code send it (with the phone number received in first response) to the sms:authenticate endpoint to obtain a JWT.
post
https://api.ratio.me
/v1/auth/otp/sms:authenticate
Authenticate a user with an SMS OTP
Request
Response
{
"phoneId": "phone-number-test-01234abc-0000-0000-0000-0123456789",
"otp": "123456",
}
{
"sessionJwt": "eyJ............"
}
cURL
curl --location --request POST 'https://api.ratio.me/v1/auth/otp/sms:authenticate' \
--header 'ratio-client-id: <YOUR_CLIENT_ID>' \
--header 'ratio-client-secret: <YOUR_CLIENT_SECRET>' \
--header 'Authorization: Bearer eyJ......' \
--header 'Content-Type: application/json' \
--data-raw '{
"otp": "123456",
"phoneId": "phone-number-test-01234abc-0000-0000-0000-0123456789"
}'
At this point you can identify the user via their User ID.
get
https://api.ratio.me
/v1/users/{userId}
This returns the current authenticated user
And return their connected wallets
get
https://api.ratio.me
/v1/users/{userId}/wallets
This returns the wallets for a user
If a user has not completed onboarding they will need to finish any remaining or all of the following steps:
You are free to complete the remaining tasks in any order, however we recommend the sequence mentioned above.
If a user has completed onboarding they are able to:
In some cases a user may be flagged in our system and prevented from using the application to buy crypto