Code Exchange Flow

DIMO Check-in

⏩ This code exchange flow works well for single account integrations, but can cause additional tech debt down the pipeline if you plan to offer functions to integrate between accounts. The Login to DIMO component only allows one account sign-in (usually one vehicle), where as the full authentication flow allows your app to connect & display multiple accounts & vehicles.

For developers that are dealing with end users that are already registered with DIMO as a Mobile App user, you can leverage the "Login to DIMO" auth service in your application. This is an alternative route to get your access_token without having users provide their public-private keys:

Step 1: Redirect to Login to DIMO

Developer Notes

Remove the .dev to access the production auth server.

To implement a user login flow, developers can simply direct users to https://auth.dev.dimo.zone/auth using the same parameters listed in the Generate Challenge step of the wallet-based auth flow, just without the address since the address will be obtained via DIMO:

1. client_id

2. domain (aka redirect_uri)

3. scope

4. and response_type

An example of the URL path with parameters:

https://auth.dev.dimo.zone/auth?client_id=${CLIENT_ID}&redirect_uri=${DOMAIN}&scope=openid email&response_type=code

This will open up a Login to DIMO flow, providing end users with options to connect via Google, Apple, or Web3 Wallets. DIMO uses Web3Auth under the hood and the login user essentially will be logging in using a 0x address.

Login to DIMO

Once logged in, the user will then be redirected to the registered domain (aka redirect_uri) and there will be a code attached to the URL params. An example is shown below:

{domain}?code=<SOME_CODE>&state=

Lastly, pass the code string marked in red to the next step to continue with the OAuth flow.

Step 2: Submit Code Exchange

Submit a Code to Exchange for the Access Token

POST https://auth.dev.dimo.zone/token

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.
grant_type*	String	This needs to be authorization_code
code*	String	The code URL parameter that you received back from the Auth server.
redirect_uri*	String	A valid redirect URI for the client, this is the domain that you set when you configure a Developer License.

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

Here's a sample cURL command of this step:

curl --location 'https://auth.dev.dimo.zone/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<client_id>' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=<code>' \
--data-urlencode 'redirect_uri=<redirect_uri>'

Developer Notes

1. If you made it this far, you should have an access_token that you can use to access the DIMO REST APIs.