Docs
Search
⌃K

User Authentication

A created user is required for sign in.

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 create a new user

For the purpose of this guide we will use:
  1. 1.
    Wallet auth
  2. 2.
    SMS auth
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 account linking guide
Authenticating with a crypto wallet requires two steps
  1. 1.
    Retrieve a challenge phrase to be signed with the users wallet.

Always use Ethereum as the "walletNetwork".

This will allow your users to interact with any supported EVM network. We currently support Ethereum and Polygon.
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>"
}'
  1. 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.

Second factor authentication

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"
}'

Identify the user

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

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