Token Exchange API Endpoints

Base URLs

Dev

https://token-exchange-api.dev.dimo.zone

Production

https://token-exchange-api.dimo.zone

---

Developer Notes

Depending on data permission, a different level of privilege is needed for the token exchange. The owner of the vehicle will also need to have granted the privileges with the API user prior to using this endpoint.

References for Privilege Sharing

Privilege	Description	Where would this be needed?
1	All-time, non-location data	Get Vehicle History, Get Vehicle Status, Get Vehicle Raw Status
2	Commands	Vehicle Commands
3	Current location
4	All-time location	List Trips, Get Vehicle History, Get Vehicle Status, Get Vehicle Raw Status
5	Verifiable Credentials	Attestation API
6	Streams	DIMO Streams

NFT Contract Address

Dev

0x45fbCD3ef7361d156e8b16F5538AE36DEdf61Da8

Production

0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF

---

Exchanging for a Privilege Token 🔐

Create a Token Exchange

POST {baseUrl}/v1/tokens/exchange

Creates a token exchange to obtain permission to a vehicle. The response will provide a short-lived token that last you 10 minutes to access additional vehicle information such as Trips and Device Data.

Headers

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

Request Body

Name	Type	Description
nftContractAddress*	String	This is the 0x address of the NFT contract. Privileges will be checked on-chain at this address. Case is not sensitive. Refer to NFT Contract Address for the address.
privileges*	[Integer]	An array of integers indicating the level of privileges provided to the token bearer. 1 - All-time, non-location data 2 - Commands 3 - Current location 4 - All-time location (For Trips API)
tokenId*	Integer	The Vehicle NFT Token ID that you are requesting permission to. This is an integer that indicates the vehicle you are inquiring about.

200: Success

{
    "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjJmMGM3NTc5ZmYyYTAzMGY0NmY1YzVkMzMyY2YyYjMyMzkxMzIxZGIifQ.eyJjb250cmFjdF9hZGRyZXNzIjoiMHhiYTU3MzhhMThkODNkNDE4NDdkZmZiZGM2MTAxZDM3YzY5YzliMGNmIiwiZXhwIjoxNzA2MDM4MTI4LCJpYXQiOjE3MDYwMzc1MjgsImlzcyI6Imh0dHBzOi8vYXV0aC1yb2xlcy1yaWdodHMuZGltby56b25lIiwicHJpdmlsZWdlX2lkcyI6WzRdLCJzdWIiOiIweGJBNTczOGExOGQ4M0Q0MTg0N2RmRmJEQzYxMDFkMzdDNjljOUIwY0YvMjE5NTciLCJ0b2tlbl9pZCI6IjIxOTU3In0.0J3HIsNeG5-JvMBcTwR8KHhTnXb31jvwjxiKVRnNaFidE0vLbyd6PtPsouniZQMIC46wzqwm2c7aZ61WhPIx9p5TB-cKcMmeKFE9mFZfBuSmvNbDd5icAvkxogWlNPki5WM2_otaGf9WtsZPlWW9GgUmBoPaRhiKB3fX7TPROcn0tTjtVir9HJKnf2CMkDwTk9rZxer8eGB6ekBSJr1aDjdqlY6HRxF_azy_rWVdzB1Wd1He9KyB3HHr1qBk5XK8d_zTA-4X3i3IEP5Z8Q3gxgoQRem70SnBNpjJjeRgAgzjfqHnKaFcjhKlxWD0h9mnpGWvd3oZLd9BPqR3WyDUCA"
}

401: Unauthorized

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

403: Forbidden

{
    "code": 403,
    "message": "<some_error_message>"
}

---

Swagger Doc

Swagger UI