Authentication

Getting authenticated as a developer

DIMO Check-in

  1. Make sure you obtain a Developer License via the Console before authentication.

  2. The Developer SDKs have functions related to authentication that can expedite the process. You can likely skip this step if you are using the SDKs.

Authentication for DIMO works in 3 steps:

  1. Generate Challenge: Generates a challenge and a state for a specific address.

  2. Sign Challenge: To sign in to obtain a JSON Web Token to the API, the signer signs 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. Submit Challenge: 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

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

Query Parameters

NameTypeDescription

client_id*

String

domain*

String

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.

{
  "state":"jot5csziknrzscg2wcbtgaofu",
  "challenge":"auth.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.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:


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));
{
  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'
}

Step 3: Submit Challenge

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

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

Request Body

NameTypeDescription

client_id*

String

state*

String

The state string returned from Step 1.

grant_type*

String

This needs to be authorization_code.

domain*

String

signature*

String

The 0x-prefixed signature obtained from Step 2.

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

Developer Notes

  1. If you made it this far, you should have an access_token that you can use to access some DIMO API endpoints. For protected API endpoints such as Telemetry API, a 2nd permissions JWT described in Token Exchange API is required.

  2. To use the access_token you received, please follow the Bearer Authentication Scheme to format your HTTP request headers. A typical format would look like { "Authorization": "Bearer <access_token>"}

Last updated