User Authentication

Getting started

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:

Wallet auth
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

Retrieve a challenge phrase to be signed with the users wallet.

{
    "walletAddress": "0x0000000000000000000000000000000000000000",
    "walletType": "EVM"
}

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.

{
    "walletAddress": "0x0000000000000000000000000000000000000000",
    "walletType": "EVM",
    "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 --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.

{
    "phoneNumber": "+14165551234",
}

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.

{
    "phoneId": "phone-number-test-01234abc-0000-0000-0000-0123456789",
    "otp": "123456",
}

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

PreviousSandbox Testing NextLink a new Signing Wallet to an Existing User

Last updated 2 years ago

Was this helpful?