Login with DIMO

Expedite your build using the Login with DIMO components

Login with DIMO is a React component SDK, providing developers with a set of pre-built, customizable building blocks for applications that integrate with DIMO. These components simplify the process of integrating Accounts API and Transactions SDK in React applications.

npm: @dimo-network/login-with-dimonpm

Login with DIMO on NPM Registry

Key Features

1. Pre-built components: The SDK offers pre-built React components that can be imported easily.

2. Flexibility with multiple integration modes: The components are designed to be flexible with multiple integration modes, such as embed, popup, or redirect.

3. Login with DIMO: End users are presented with a email login field, and an OTP will be sent to the email for authentication. A passkey prompt will be triggered after the OTP for either setup or login. .

4. Integration with the Transactions SDK: The React components seamlessly integrate with the Transactions SDK, allowing you to leverage the SDK's features and functionalities such as creating a vehicle and sharing vehicle permissions, etc.

This SDK utilizes Accounts API for developers and manages to connect to the user's DIMO account. Once connected, it further integrates with the Transactions SDK to perform operations associated with the user's vehicles and permissions.

Login with DIMO Button Component

Popup Component

Embedded Component

Using the SDK

1

Installation

npm install @dimo-network/login-with-dimo

2

Initialization

import { 
  initializeDimoSDK, 
  useDimoAuthState
} from "@dimo-network/login-with-dimo";

// Initialize the State Variables
const { 
  isAuthenticated, 
  getValidJWT, 
  email, 
  walletAddress, 
  getEmail 
} = useDimoAuthState();

// Initialize the SDK
initializeDimoSDK({
  clientId: "<dev_license_clientId>",
  redirectUri: "<dev_license_redirectUri>",
  // OPTIONAL
  // apiKey: "<dev_license_apiKey>",
  // environment: "<environment>", 
});

Parameter	Type	Details
clientId*	String	A valid client ID registered with your Developer License.
redirectUri*	String	A valid redirect URI registered with your Developer License.
apiKey	String	Optional API key of your Developer License. This is currently not in use and reserved for future applications.
environment	String	Environment where your app is registered to. Defaults to production if not indicated. Supports development or production at the moment.

3

Import the Components

import { 
    LoginWithDimo, 
    ShareVehiclesWithDimo,
    ExecuteAdvancedTransactionWithDimo
} from "@dimo-network/login-with-dimo";

In your React app, import the different components as needed and drop in the component of interest with the following input configurations.

4

Configure the Components

Depending on the component you're looking to surface, choose between the following inputs:

Inputs for LoginWithDimo & ShareVehiclesWithDimo

Parameter	Type	Details
mode*	String	One of the three available modes: popup, embed, or redirect.
onSuccess*	Callback	Callback function called when the authData is returned for popup and embed modes. Example for authData: { token: <access_token> } For redirect mode, the access_token is in the redirect URI. Example for redirect: https://your-site.com/redirect?token=<access_token>&email=<user_email>
onError*	Callback	Callback function called when error occurs.
permissionTemplateId	String	Optional template ID of the SACD permissions template on IPFS. If undefined, no permissions flow will be triggered for the end users. For ShareVehiclesWithDimo component, this is required as sharing requires permission templates.
vehicles	[String]	Optional array of vehicle tokenId's to target for the logged in user. If vehicles is not provided, the flow will pull all available vehicles. This also filters out any vehicle tokenId that doesn't belong to the signed-in user.
vehicleMakes	[String]	Optional array of vehicle makes to filter for compatibility with your app. If vehicleMakes is not provided, all available vehicles will be marked as compatible. Example: [ 'Tesla', 'Audi', 'Lexus' ]
expirationDate	[String]	Optional parameter to explicitly specify an expiration date for permissions in the ISO8601 format (YYYY-MM-DD).
authenticatedLabel	[String]	Optional parameter to override default button label text for authenticated users.
unAuthenticatedLabel	[String]	Optional parameter to override default button label text for unauthenticated users.

Inputs for ExecuteAdvancedTransactionWithDimo

Parameter	Type	Details
mode*	String	One of the three available modes: popup, embed, or redirect.
onSuccess*	Callback	Callback function called when data is returned for popup and embed modes. Example: data: { token: <access_token>; transactionHash: <tx_hash>; transactionReceipt: <tx_receipt>; }
onError*	Callback	Callback function called when error occurs.
address*	String	The 0x address of the smart contract being executed.
abi*	Any	An array of JSON representing the ABI of the advanced functions of interest.
functionName*	String	The name of the function being called.
args*	[String]	The arguments being passed into the function call.
value	String	Optional number in wei of the native currency sent as a part of the transaction.

5

Build your app

Now that you've reached this step, all you need to do is finish building your app and interact with the components. Depending on what you wish your users see, reconfigure as necessary.

6

Voila, you're all done 🎉

Congratulations for reaching this step, you're one huge step closer to launching an integration with DIMO!

Don't Use React?

Developer Notes

If you don't use the React framework, you can still build a button in your tech stack and redirect the users to the following URLs depending on the flow of interest.

Login Flow Only (No Permissions Requested)

https://login.dimo.org/?clientId=<clientId>&redirectUri=<redirectUri>

Check it working with an example

Login + Permissions Flow (Default Expiration: 1 year from now)

https://login.dimo.org/?clientId=<clientId>&redirectUri=<redirectUri>&permissionTemplateId=<templateId>&entryState=VEHICLE_MANAGER

Check it working with an example

Login + Permissions Flow with Custom Expiration (ISO8601 Format YYYY-MM-DD)

https://login.dimo.org/?clientId=<clientId>&redirectUri=<redirectUri>&permissionTemplateId=<templateId>&entryState=VEHICLE_MANAGER?expirationDate=<date>

Check it working with an example

State Variables

DimoAuthProvider is used to get the auth state value from the SDK, as well as to keep track of the user email, Global Account public address, and the User JWT.

Any components that require this value should be wrapped in the DimoAuthProvider, as follows:

<DimoAuthProvider>
    <SomeComponentThatNeedsDimoState/>
<DimoAuthProvider/>

Component Types

LoginWithDimo

When permissionTemplateId are provided:

User has no vehicles connected	User has all vehicles shared	User has some vehicles not shared
Shows "No vehicles connected" with a Continue Button	Shows "All vehicles have been shared" with a Continue Button	Show list of all vehicles for permission sharing

When permissionTemplateId are NOT provided. Since permissions are not requested, developers can couple this with the ShareVehiclesWithDimo component post-login:

User has no vehicles connected	User has all vehicles shared	User has some vehicles not shared
Skips permission sharing	Skips permission sharing	Skips permission sharing

ShareVehiclesWithDimo

This is a decoupled component that developers can use post-login, will trigger login if user isn't logged in:

User has no vehicles connected	User has all vehicles shared	User has some vehicles not shared
Shows "No vehicles connected" with a Continue Button	Shows "All vehicles have been shared" with a Continue Button	Show list of all vehicles for permission sharing

ExecuteAdvancedTransactionsWithDimo

This is a decouple component that developers can use post-login, will trigger login if user isn't logged in.

Integration Modes

Mode	Description
embed	The embed mode basically embeds an iframe HTML element that surfaces the Login with DIMO interface. In this mode, the JWT returned is considered a 3rd party cookie so be aware of the user's browser settings. By default, browsers like Chrome and Firefox allows 3rd party cookies, but browsers like Safari and Brave blocks them.
popup	The popup mode surfaces a React button component that opens up a browser pop-up (new window) containing the Login with DIMO interface.
redirect	The redirect mode surfaces a React button component that redirects the users to the Login with DIMO interface.

Usage Example

<LoginWithDimo
    mode="popup"
    onSuccess={(authData) => console.log("Success:", authData)}
    onError={(error) => console.error("Error:", error)}
    // This will control if your users are asked to share vehicles, as part of the login flow. "1" is the template for all SACD permissions
    permissionTemplateId={permissionsEnabled ? "1" : undefined}
    // Optionally, specify vehicles (uncomment the line below to use it)
    // vehicles={["585","586"]}  // Specify the vehicles to be accessed after login            
/>

 <ShareVehiclesWithDimo
    mode="popup"
    onSuccess={(authData) => console.log("Success:", authData)}
    onError={(error) => console.error("Error:", error)}
    //REQUIRED: "1" is the template for all SACD permissions
    permissionTemplateId={"1"}
    // OPTIONAL, specify vehicles (uncomment the line below to use it)
    // vehicles={["585","586"]}  // Specify the vehicles to be accessed when triggered
    expirationDate="2062-12-12T18:51:00Z" // ISO 8601 format 
    // OPTIONAL, defaults to 1 year if not specified  
/>      

<ExecuteAdvancedTransactionWithDimo
    mode="popup"
    onSuccess={(data: any) => console.log("Success:", data)}
    onError={(error: any) => console.error("Error:", error)}
    address="0x21cFE003997fB7c2B3cfe5cf71e7833B7B2eCe10"
    value="0"
    abi={sampleAbi} //Some sample ABI required
    functionName="transfer"
    args={["0x62b98e019e0d3e4A1Ad8C786202e09017Bd995e1", "0"]}
/>