Token Exchange API

DIMO Check-in

Permissions is the new privileges. You may have noticed this name change on the DIMO Network, but we've essentially migrated privileges from the Vehicle NFT to an asset-agnostic permissions smart contract under SACD.

Usage of this API endpoint can be done via Developer SDKs.

This is a private API endpoint that is optional for developers using the DIMO Network. It handles the exchange to obtain a Vehicle JWT. By (users) sharing permissions to an app, the app can now request for vehicle data on behalf of the users.

Base URLs

Production

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

---

Privilege Definitions

Privilege	Description
1	All-time, non-location data
2	Commands
3	Current location
4	All-time location
5	View VIN credentials
6	Live data streams
7	Raw data
8	Approximate location

---

Exchanging for a Vehicle JWT

Create a Token Exchange

POST {baseUrl}/v1/tokens/exchange

Creates a token exchange to obtain a Vehicle JWT. The response will provide a short-lived token that last you 10 minutes to access additional vehicle information such as Trips and Telemetry data

Headers

Name	Type	Description
Authorization*	String	Developer JWT in Bearer Authentication format.

Request Body

Name	Type	Description
nftContractAddress*	String	The Vehicle NFT address, in the Production environment, this is 0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF.
privileges*	[Integer]	An array of integers indicating the level of privileges provided to the token bearer. Refer to privilege definitions.
tokenId*	Integer	The Vehicle 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>"
}

Token Exchange: Data SDK Function Calls

TypeScript

await dimo.tokenExchange.exchange({
    developerJwt, 
    tokenId
});

Python

dimo.token_exchange.exchange(dev_jwt, token_id)

C#

await dimoClient.TokenExchangeService.GetPrivilegeTokenAsync(
    accessToken,
    privileges,
    tokenId
);

Entity Types

Token

Token is a string that serves as the access_token to perform operations on a specific vehicle's data. This is used to gate-keep data that are associated with a specific vehicle. The Vehicle JWT here is scoped to individual vehicle and short-lived, with an expiration time of 10 minutes.