Devices API

Vehicle (User Device) Queries 🔐

List All Devices Associated with the User

GET {baseUrl}/v1/user/devices/me

Lists all devices associated with the authenticated user.

Headers

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

200: OK

401: Unauthorized

500: Internal Server Error

List All Devices Shared with the User

GET {baseUrl}/v1/user/devices/shared

Lists all devices shared with the authenticated user.

Headers

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

200: OK

401: Unauthorized

500: Internal Server Error

Device Commands 🔐

Get Aftermarket Device Data by Device Serial Number

GET {baseUrl}/v1/aftermarket/device/by-serial/{serial}

Retrieves the aftermarket device data for the device serial number.

Headers

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

200: OK

{
    "isUpdated": true,
    "deviceId": "",
    "unitId": "24601960806",
    "dockerReleases": null,
    "hwRevision": "",
    "template": 0,
    "lastCommunication": "0001-01-01T00:00:00Z",
    "releaseVersion": "",
    "shouldUpdate": false,
    "tokenId": 13986,
    "ethereumAddress": "0xddf4c4ec0023d957f4dbefebbd158bf6e02be7c8",
    "ownerAddress": "0xf9D26323Ab49179A6d57C26515B01De018553487",
    "beneficiaryAddress": "0xf9d26323ab49179a6d57c26515b01de013253787",
    "claim": {
        "status": "Confirmed",
        "hash": "0xa4944c7a148810c196d034af682d39dbe653e6eb56f13924dec2852e122f674f",
        "createdAt": "2024-01-02T23:37:56.783001Z",
        "updatedAt": "2024-01-02T23:38:13.557678Z"
    },
    "pair": {
        "status": "Confirmed",
        "hash": "0x3552c112c4281822eed1c45f0ee23c53969acfe8961419d673bdb504234d61d7",
        "createdAt": "2024-02-03T22:20:58.597529Z",
        "updatedAt": "2024-02-03T22:21:18.823898Z"
    },
    "manufacturer": {
        "tokenId": 142,
        "name": "Hashdog"
    }
}

500: Internal Server Error

401: Unauthorized Invalid or expired JWT.

Get Aftermarket Device Data by Device Serial Number

POST {baseUrl}/v1/aftermarket/device/by-serial/{serial}/update

Retrieves the aftermarket device data for the device serial number.

Headers

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

200: OK

{
    "isUpdated": true,
    "deviceId": "",
    "unitId": "24601960806",
    "dockerReleases": null,
    "hwRevision": "",
    "template": 0,
    "lastCommunication": "0001-01-01T00:00:00Z",
    "releaseVersion": "",
    "shouldUpdate": false,
    "tokenId": 13986,
    "ethereumAddress": "0xddf4c4ec0023d957f4dbefebbd158bf6e02be7c8",
    "ownerAddress": "0xf9D26323Ab49179A6d57C26515B01De018553487",
    "beneficiaryAddress": "0xf9d26323ab49179a6d57c26515b01de013253787",
    "claim": {
        "status": "Confirmed",
        "hash": "0xa4944c7a148810c196d034af682d39dbe653e6eb56f13924dec2852e122f674f",
        "createdAt": "2024-01-02T23:37:56.783001Z",
        "updatedAt": "2024-01-02T23:38:13.557678Z"
    },
    "pair": {
        "status": "Confirmed",
        "hash": "0x3552c112c4281822eed1c45f0ee23c53969acfe8961419d673bdb504234d61d7",
        "createdAt": "2024-02-03T22:20:58.597529Z",
        "updatedAt": "2024-02-03T22:21:18.823898Z"
    },
    "manufacturer": {
        "tokenId": 142,
        "name": "Hashdog"
    }
}

500: Internal Server Error

401: Unauthorized Invalid or expired JWT.

Document Operations 🔐

List All Documents for the User

GET {baseUrl}/v1/documents

Retrieves a list containing all documents for an authorized user.

Headers

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

200: OK Successfully retrieved a list of all documents.

401: Unauthorized Invalid or expired JWT.

500: Internal Server Error

Get a Document for the User by Document ID

GET {baseUrl}/v1/documents/{documentId}

Retrieves a document for an authorized user with the provided document ID.

Path Parameters

Name	Type	Description
documentId*	String

Headers

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

200: OK Successfully retrieved a document.

401: Unauthorized Invalid or expired JWT.

500: Internal Server Error

Download a Document for the User by Document ID

GET {baseUrl}/v1/documents/{documentId}/download

Downloads a document for an authorized user with the provided document ID.

Path Parameters

Name	Type	Description
documentId*	String

Headers

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

200: OK Successfully downloaded a document.

401: Unauthorized Invalid or expired JWT.

500: Internal Server Error

Upload a New Document for the User

POST {baseUrl}/v1/documents

Uploads a new document for an authorized user.

⚠️ Body type needs to be form-data

Headers

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

Request Body

Name	Type	Description
file*	File	The file to upload.
name*	String	The name of the document.
type*	String	The type of the document.
userDeviceId	String	Optional user device ID.

200: OK Successfully uploaded a document.

401: Unauthorized Invalid or expired JWT.

500: Internal Server Error

Delete a Document for the User by Document ID

DELETE {baseUrl}/v1/documents/{documentId}

Deletes a document for an authorized user with the provided document ID.

Path Parameters

Name	Type	Description
documentId*	String

Headers

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

401: Unauthorized Invalid or expired JWT.

500: Internal Server Error

204: No Content Successfully removed a document.

Aftermarket Device Operations

Unclaim the Device by Device Serial Number

POST {baseUrl}/v1/aftermarket/device/by-serial/{serial}/commands/unclaim

Dev-only endpoint for removing a claim. Removes the flag on-chain and clears the owner in the database.

Path Parameters

Name	Type	Description
serial*	String

Headers

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

204: No Content

401: Unauthorized Invalid or expired JWT.

500: Internal Server Error

---

Pairing a Vehicle with Aftermarket Device 🔐

[Deprecating] Get the Pairing Payload by User Device ID

GET {baseUrl}/v1/user/devices/{userDeviceId}/aftermarket/commands/pair

Retrieves the EIP-712 payload for user device <> vehicle pairing.

Path Parameters

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API

Headers

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

200: Success

{
  "domain": {
    "chainId": {},
    "name": "string",
    "salt": "string",
    "verifyingContract": "string",
    "version": "string"
  },
  "message": {
    "additionalProp1": {}
  },
  "primaryType": "string",
  "types": {
    "additionalProp1": [
      {
        "name": "string",
        "type": "string"
      }
    ],
    "additionalProp2": [
      {
        "name": "string",
        "type": "string"
      }
    ],
    "additionalProp3": [
      {
        "name": "string",
        "type": "string"
      }
    ]
  }
}

401: Unauthorized

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

500: Internal Server Error

Sign the Pairing Payload by User Device ID to Pair Device

POST {baseUrl}/v1/user/devices/{userDeviceId}/aftermarket/commands/pair

Pairs the aftermarket device identified by User Device ID, signs the pairing payload with a device signature and a user signature while sending to the blockchain.

Path Parameters

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API

Headers

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

Request Body

Name	Type	Description
userSignature*	Object	{ "aftermarketDeviceSignature": [ 0 ], "externalId": "string", "signature": [ 0 ] }

204: No Content

401: Unauthorized

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

500: Internal Server Error

---

Unpairing a Vehicle with Aftermarket Device 🔐

[Deprecating] Get the Unpairing Payload by User Device ID

GET {baseUrl}/v1/user/devices/{userDeviceId}/aftermarket/commands/unpair

Retrieves the EIP-712 payload for user device <> vehicle pairing.

Path Parameters

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API

Headers

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

200: Success

{
  "domain": {
    "chainId": {},
    "name": "string",
    "salt": "string",
    "verifyingContract": "string",
    "version": "string"
  },
  "message": {
    "additionalProp1": {}
  },
  "primaryType": "string",
  "types": {
    "additionalProp1": [
      {
        "name": "string",
        "type": "string"
      }
    ],
    "additionalProp2": [
      {
        "name": "string",
        "type": "string"
      }
    ],
    "additionalProp3": [
      {
        "name": "string",
        "type": "string"
      }
    ]
  }
}

401: Unauthorized

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

500: Internal Server Error

Sign the Unpairing Payload by User Device ID to Unpair Device

POST {baseUrl}/v1/user/devices/{userDeviceId}/aftermarket/commands/pair

Unpairs the aftermarket device identified by User Device ID, signs the unpairing payload with a device signature and a user signature while sending to the blockchain.

Path Parameters

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API

Headers

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

Request Body

Name	Type	Description
userSignature*	Object	{ "aftermarketDeviceSignature": [ 0 ], "externalId": "string", "signature": [ 0 ] }

204: No Content

401: Unauthorized

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

500: Internal Server Error

---

On-chain Queries 🔏

Developer Notes

The following endpoints are publicly available providing on-chain metadata.

Get Synthetic Device Metadata by Token ID

GET {baseUrl}/v1/synthetic/device/{tokenId}

Retrieves the synthetic device metadata for the given token ID.

Path Parameters

Name	Type	Description
tokenId*	String	Device token ID, this is the token ID of your device NFT. This is publicly available to query in the Identity API.

200: Success

500: Internal Server Error

Get Aftermarket Device Metadata by Token ID

GET {baseUrl}/v1/aftermarket/device/{tokenId}

Retrieves the aftermarket device metadata for the given token ID. This returns the same data as Get Aftermarket Device Metadata by Ethereum Address.

Path Parameters

Name	Type	Description
tokenId*	String	Device token ID, this is the token ID of your device NFT. This is publicly available to query in the Identity API.

200: Success

500: Internal Server Error

Get Aftermarket Device Image by Token ID

GET {baseUrl}/v1/aftermarket/device/{tokenId}/image

Retrieves the aftermarket device image for the given token ID.

Path Parameters

Name	Type	Description
tokenId*	String	Device token ID, this is the token ID of your device NFT. This is publicly available to query in the Identity API.

200: Success

500: Internal Server Error

Get Aftermarket Device Metadata by Ethereum Address

GET {baseUrl}/v1/aftermarket/device/by-address/{address}

Retrieves the aftermarket device metadata for the given 0x Ethereum address. This returns the same data as in #get-aftermarket-device-metadata-by-token-id

Path Parameters

Name	Type	Description
address*	String	Ethereum address.

200: Success

500: Internal Server Error

---