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

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. Retrieve a challenge phrase to be signed with the users wallet.

Request

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

Response

{
    "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>",
    "walletType": "EVM"
}'

2. Then authenticate that signature with the users wallet.

Request

{
    "walletAddress": "0x0000000000000000000000000000000000000000",
    "walletType": "EVM",
    "signature": "2djd2cFZ9VU2zDWvUGqeHwvbiJZfTt3BMzDctDsEW7vM2QUTgTHjeM2rpFX9ZULeic3KptUh5ehipXDFcK5ecYiX"
}

Response

{
    "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>",
    "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

{
    "phoneNumber": "[phone]",
}

Response

{
    "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": "[phone]"
}'

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

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

Response

{
    "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.

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:

• Have a deposit address assigned

• Be KYC approved

• Have a verified bank account

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:

• Re-link a bank account

• Replace an existing bank account

• Remove an existing bank account

• Buy crypto

• View their transaction activity

Scenario 3

In some cases a user may be flagged in our system and prevented from using the application to buy crypto

• View their transaction activity

• Re-link a bank account

• Replace an existing bank account

• Remove an existing bank account