A
Getting started
To get started we require two factors of user-authentication* to receive a JWT token to be passed in the header.
For sign in you need to re-use whatever two factors you used to
For the purpose of this guide we will use:
You can see more information on our authentication methods here
First factor authentication
This wallet auth needs to happen with the same wallet used in the create new user flow
If a user is attempting to sign in with a new wallet, please follow our
Authenticating with a crypto wallet requires two steps
Retrieve a challenge phrase to be signed with the users wallet.
Request Response
Copy {
"walletAddress": "0x0000000000000000000000000000000000000000",
"walletType": "EVM"
}
Copy {
"challenge": "Signing in with Ratio: pUQikKqqBq1brTwt1oHhUJwlOTfshzfMEAsJaH7x1MOdN7QMOooFfj-Aujmi7sb0wJnvYqtmZtlszKdH"
} cURL
Copy 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>",
"walletType": "EVM"
}' Then authenticate that signature with the users wallet.
Request Response
Copy {
"walletAddress": "0x0000000000000000000000000000000000000000",
"walletType": "EVM",
"signature": "2djd2cFZ9VU2zDWvUGqeHwvbiJZfTt3BMzDctDsEW7vM2QUTgTHjeM2rpFX9ZULeic3KptUh5ehipXDFcK5ecYiX"
}
Copy {
"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
Copy 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>",
"walletType": "EVM",
"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.
Second factor authentication
First we need to send a one-time code to the user using the phone number they provided in sign up.
Request Response
Copy {
"phoneNumber": "+14165551234",
}
Copy {
"phoneId": "phone-number-test-01234abc-0000-0000-0000-0123456789",
"phoneMask": "1234"
} cURL
Copy 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.
Request Response
Copy {
"phoneId": "phone-number-test-01234abc-0000-0000-0000-0123456789",
"otp": "123456",
}
Copy {
"sessionJwt": "eyJ............"
} cURL
Copy 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"
}' Identify the user
At this point you can identify the user via their User ID.
And return their connected wallets
Next steps
Scenario 1
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.
Scenario 2
If a user has completed onboarding they are able to:
Scenario 3
In some cases a user may be flagged in our system and prevented from using the application to buy crypto
