Wallet-Based Authentication Flow

DIMO Check-in

🥁 Make sure you go through the Developer Licensing process before authentication.

The 3-step wallet-based web3 authentication flow is an authentication process tailored for decentralized applications using Ethereum blockchain technology.

Here's how web3 auth works with DIMO:

1. Key Generation: A user generates a unique pair of public and private keys, which serve as their digital identity. The private key is used to sign transactions and access their accounts. The public key is shared publicly and is used to identify the user.

2. Signing In: To sign in to obtain a JSON Web Token to the API, the user uses their private key to sign a cryptographic message, proving that they are the owner of the associated public key. This process is known as signing in with a digital signature.

3. Access Control: The public key is then used to verify the user's digital signature and grant or deny access to the resources with the permissions set.

DIMO's implementation of the web3 signature mechanism for a backend application can be completed with the 3 steps below:

Step 1: Generate Challenge

Generate Web3 Challenge

POST https://auth.dev.dimo.zone/auth/web3/generate_challenge

Query Parameters

Name	Type	Description
client_id*	String	Configured client identifier, this is the 0x client identifier received when you issue a Developer License.
domain*	String	A valid redirect URI for the client, this is the domain that you set when you configure a Developer License.
scope*	String	Space-separated list of scopes, this needs to be openid email
response_type*	String	This needs to be code.
address*	String	A hex-encoded, 0x-prefixed, 20-byte Ethereum address (case insensitive). This is the contract address of your Developer License as you are assuming the role of signer of the license. The value is essentially the same as the client_id.

200: Success

{
  "state":"jot5csziknrzscg2wcbtgaofu",
  "challenge":"auth.dev.dimo.zone wants you to sign in with your Ethereum account:\n<YOUR_ADDRESS>\n\n<host> is asking you sign in.\n\nURI: https://auth.dev.dimo.zone\nVersion: 1\nChain ID: 1\nNonce: 4P8AfZTqj9QwDM8tKc2vfIqQogxpXK\nIssued At: 2024-01-08T15:31:15Z"
}

Step 2: Sign Challenge

You will need to format the challenge string from Step 1 to hex and prefix it with 0x, combine that with the enabled signer's private_key , in order to sign the Ethereum transaction and obtain a 65-byte signature.

To sign the challenge, you will need to use a library in your preferred programming language to sign Ethereum transactions and messages with local private keys. We have provided a few language examples as a starter:

---

NodeJS

const web3 = require('web3');

const msg = "<challenge>"
const privateKey = "<signer_private_key>"
const formattedKey = '0x' + Buffer.from(privateKey, 'utf8');

console.log(web3.eth.accounts.sign(msg, formattedKey));

Python

import siwe
from siwe import SiweMessage

from eth_account import Account
from eth_account.messages import encode_defunct
from eth_utils.curried import to_bytes

msg = "<challenge>"
private_key = "<private_key>"

# No need to hexify when using siwe-py as the purpose of it is to help with formatting & verifying
# This is the pure Python way: hex_msg = '0x' + msg.encode().hex()

try:
    # Format the message
    message: SiweMessage = SiweMessage(message=msg)

    sn = encode_defunct(to_bytes(text=msg))
    acct = Account.from_key(private_key)
    # Actual signing of the message
    sm = acct.sign_message(sn)
    print(sm)

except ValueError as e:
    # Invalid message
    print("Authentication attempt rejected - invalid message.")
except siwe.ExpiredMessage:
    print("Authentication attempt rejected - expired message.")
except siwe.DomainMismatch:
    print("Authentication attempt rejected - domain mismatch.")
except siwe.NonceMismatch:
    print("Authentication attempt rejected - nonce mismatch.")
except siwe.MalformedSession as e:
    # e.missing_fields contains the missing information needed for validation
    print("Authentication attempt rejected - malformed session.")
except siwe.InvalidSignature:
    print("Authentication attempt rejected - invalid signature.")

NodeJS

{
  message: 'auth.dimo.zone wants you to sign in with your Ethereum account:\n' +
    '0xf9D26323Ab49179A6d57C26515B01De018553666\n' +
    '\n' +
    'app.dimo.zone is asking you sign in.\n' +
    '\n' +
    'URI: https://auth.dimo.zone\n' +
    'Version: 1\n' +
    'Chain ID: 1\n' +
    'Nonce: EXVgxuxMiNfdWzwIcQU4XZ79zzwX6L\n' +
    'Issued At: 2024-01-22T15:34:47Z',
  messageHash: '0x293013bcae66e507384b791b35bd3701284b613887fc11d3a6debcde394c66db',
  v: '0x1c',
  r: '0xccd996ee0f2d18944034f29e5a9565158202d8d66194adcbe0c13eba96feb18e',
  s: '0x1783254ec656186cd1461693969c10aff0014f4690ee2f83781dbf8c4c657ef3',
  signature: '0xcbd996ee0f2d18944034f29e5a9565158202d8d66194adcbe0c13eba96feb18e1783254ec656186cd1461693969c10aff0014f4690ee2f83781dbf8c4a657ef31c'
}

Python

SignedMessage(messageHash=HexBytes('0x629749f84ee0d301f8eb02f3ef897b0c0a4553d2fdxd1fa0ea5cbbb6ff8bdfd5'), r=48064598734910045938712268846365002327886250846331651560012768739017714013389, s=54468135635475555126928311975236101130284121664770021136367631881584318718503, v=27, signature=HexBytes('0x6a43994c94195bf873b1025ae5778768a6311fb846bc21f5aeffc71f058394cd786bdf4d27e43e9a2358a4a0018f1af0333cbbf6318d6dd2be929e5f3fc9a2271b'))

Step 3: Submit Challenge

Submit Web3 Challenge

POST https://auth.dev.dimo.zone/auth/web3/submit_challenge

Use x-www-form-urlencoded for body parameters.

Request Body

Name	Type	Description
client_id*	String	Configured client identifier, this is the 0x client identifier received when you issue a Developer License.
state*	String	The state string returned from Step 1.
grant_type*	String	This needs to be authorization_code.
domain*	String	A valid redirect URI for the client, this is the domain that you set when you configure a Developer License.
signature*	String	The 0x-prefixed signature obtained from Step 2.

200: Success

{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ijc4ZjVkNDk3ZjVjZDM3MzljYjNhYmZhZDExZjRhZWQ2ZWQxNmNhMWYifQ.eyJpc3MiOiJodHRwczovL2F1dGguZGV2LmRpbW8uem9uZSIsInByb3ZpZGVyX2lkIjoid2ViMyIsInN1YiI6IkNpb3dlR1k1UkRJMk16SXpRV0kwT1RFM09VRTJaRFUzUXpJMk5URTFRakF4UkdVd01UZzFOVE0zT0RjU0JIZGxZak0iLCJhdWQiOiJ2ZWhpY2xlLWdlbml1cyIsImV4cCI6MTcwNTkzNTg5MCwiaWF0IjoxNzA0NzI2MjkwLCJhdF9oYXNoIjoiQnBVZXJtcmJMMUlNVkxNdXpELW93USIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiZXRoZXJldW1fYWRkcmVzcyI6IjB4ZjlEMjYzMjNBYjQ5MTc5QTZkNTddMjY1MTVCMDFEZTAxODU1Mzc4NyJ9.BrZeLozHwFxQoyTnpe9TVjoFFyqh3xs2xi6KQrguQGyyWoqFr03SjDCbY_Les6IUI9JD_xWf9bu04w82LD0NqsnO7nqrYwrVwriYUmh1cZskZPUDrL5_kMaN0FxQa-ea9g4ruVEXLU_aM206q2Wp7qqyjd5AhuPAgqAL6mDGviGXr2lJYfxrs0eclO9-w4Z4XO0hRkLO_ODhCDrBeKcwPHEmhTNH6Vw0ReI_05FwIFzz_biIpS6rj45F0nSLrMcJx-2UD9upaMDzLwA_9QPoXzoA3hfdPNKGPU0KEgMJF9thFa2K0daqXqAMXUkxwOSSYWdn58Z8NJGFWN6bzyJqC3",
    "token_type": "bearer",
    "expires_in": 1209599,
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ijc4ZjVkNDk3ZjVjZDM3MzljYjNhYmZhZDExZjRhZWQ2ZWQxNmNhMWYifQ.eyJpc3MiOiJodHRwczovL2F1dGguZGV2LmRpbW8uem9usSIsInByb3ZpZGVyX2lkIjoid2ViMyIsInN1YiI6IkNpb3dlR1k1UkRJMk16SXpRV0kwT1RFM09VRTJaRFUzUXpJMk5URTFRakF4UkdVd01UZzFOVE0zT0RjU0JIZGxZak0iLCJhdWQiOiJ2ZWhpY2xlLWdlbml1cyIsImV4cCI6MTcwNTkzNTg5MCwiaWF0IjoxdzA0NzI2MjkwLCJhdF9oYXNoIjoibGdyZGx5UXhWVWlMY0o1ZWxmTU1odyIsImNfaGFzaCI6IkZid2NTVUlJcnl0S2xVblZHWjE4Z3ciLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImV0aGVyZXVtX2FkZHJlc3MiOiIweGY5RDI2MzIzQWI0OTE3OUE2ZDU3QzI2ETE1QjAxRGUwMTg1NTM3ODcifQ.afO4QhbCfzWZpB_VQhTuJBONA8hYMc8Dw97kNdDBwbYWCIZ_PFzIRUPJe75k19Y0oKm8hNeadyzV36x4uvv4wagfjEPXcttqzoiRrnFjwX5tHZgNaRSznBf6W6PoNzkx7GyGWmeW_AtV3Y4g_fDhC2PKVZeWlw346Prchf_mLDuC5d6HSydu4LoSGHRVhMXlbbwoXGcc3Jui-wMxli8gYx1N__5DXiGvasZgmZefRq9DqPhd5Nlp0AV7bDSSLVJOUZJybbHT153les-_IzMlyqowxrAaJl9ENk5ME5ak4g_gHUpJzPQAf3oe61K-sYKNUYcguah73xfysmbWc_bFsg"
}

400: Bad Request

{
    "status": 400,
    "message": "Requested resource does not exist."
}

Developer Notes

1. If you made it this far, you should have an access_token that you can use to access the DIMO REST API endpoints that are marked with 🔐. For privileged API endpoints marked with 🔏, please refer to the 2nd privilege JWT described in Token Exchange API.

2. Please send a GET request to the Users API Endpoint to provision the authenticated user prior to doing anything, learn more about setting up the user in Users API.