Users API Endpoints

Base URLs

Dev

https://users-api.dev.dimo.zone

Production

https://users-api.dimo.zone

---

Basic User Operations 🔐

Get Authenticated User

GET {baseUrl}/v1/user

Retrieves user attributes for the authenticated user.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

{
    "id": "CioweGY5RDI2MzIzQWI0OTE3OUE2ZDU3QzI2NTE1QjAxRGUwMTg1NTM3ODcSBHdlYjM",
    "email": {
        "address": null,
        "confirmed": false,
        "confirmationSentAt": null
    },
    "web3": {
        "address": "0xf9D26323Ab49179A6d57C26515B01De018553787",
        "confirmed": true,
        "used": true,
        "inApp": false,
        "challengeSentAt": null
    },
    "createdAt": "2024-01-18T23:19:22.693833Z",
    "countryCode": null,
    "agreedTosAt": null,
    "referralCode": "GAILPP",
    "referredBy": null,
    "referredAt": null
}

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

403: Forbidden

Update Authenticated User

PUT {baseUrl}/v1/user

Updates/modifies attributes for the authenticated user.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
userUpdateRequest*	Object	See example below for data structure: { "countryCode": "USA", "email": { "address": "[e-mail]" }, "web3": { "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "inApp": true } }

200: Success

{
  "agreedTosAt": "2021-12-01T09:00:41Z",
  "countryCode": "USA",
  "createdAt": "2021-12-01T09:00:00Z",
  "email": {
    "address": "[e-mail]",
    "confirmationSentAt": "2021-12-01T09:01:12Z",
    "confirmed": false
  },
  "id": "ChFrb2JsaXR6QGRpbW8uem9uZRIGZ29vZ2xl",
  "referralCode": "ANB95N",
  "referredAt": "2021-12-01T09:00:41Z",
  "referredBy": "0x3497B704a954789BC39999262510DE9B09Ff1366",
  "web3": {
    "address": "0x142e0C7A098622Ea98E5D67034251C4dFA746B5d",
    "challengeSentAt": "2021-12-01T09:01:12Z",
    "confirmed": false,
    "inApp": false,
    "used": false
  }
}ss

400: Bad Request

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

403: Forbidden

Delete Authenticated User

DELETE {baseUrl}/v1/user

Deletes the authenticated user. Throws a 409 error if the authenticated user has device registered.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

204: No Content

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

403: Forbidden

409: Conflict

---

2FA Email Confirmation Flow 🔐

Send a Confirmation Email

POST {baseUrl}/v1/user/send-confirmation-email

Sends a confirmation email to the registered email address of the authenticated user. This is the initiation step of the 2-factor authentication (2FA).

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

204: No Content

400: Bad Request

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

403: Forbidden

500: Internal Server Error

Submit an Email Confirmation Key

POST {baseUrl}/v1/user/confirm-email

Confirms the receipt of the confirmation email, this is the completion step of the 2-factor authentication (2FA).

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
confirmEmailRequest*	Object	Specifies the key from the email. This needs to be in the format of { "key": "<6-digit-number>" }

204: No Content

400: Bad Request

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

403: Forbidden

---

Web3 User Auth Flow 🔐

Generate a Challenge for the User to Sign

POST {baseUrl}/v1/user/web3/challenge/generate

Generates a Web3 challenge message with an expiration timestamp for the user to sign.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

400: Bad Request

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

Submit a Signed Challenge

POST {baseUrl}/v1/user/web3/challenge/submit

Confirms ownership of an Ethereum address.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
confirmEthereumRequest*	Object	This needs to be in the format of { "signature": "<signed_challenge_msg>" }

200: Success

400: Bad Request

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

---

Miscellaneous 🔐

Agree to Terms of Service

POST {baseUrl}/v1/user/agree-tos

Sends a confirmation agreeing to the current Terms of Service.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

204: No Content

400: Bad Request

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

Submit a Referral Code

POST {baseUrl}/v1/user/submit-referral-code

Submits a referral code from another user. The request sends the referral code, validates, and stores it for referral rewards recognition.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

Request Body

Name	Type	Description
submitReferralCodeRequest*	Object	This needs to be in the format of { "referralCode": "<6-digit-code>" }

200: Success

400: Bad Request

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

500: Internal Server Error

---

Swagger Doc

Swagger UI