Authentication¶

Access to the API is secured. You must first authenticate to obtain a token, which is required for any use of the API.

There are two authentication use cases:

User accounts managed by the application: users are unknown to Carmoove, only the appId and appKey provided by Carmoove are needed for authentication. All data for vehicles linked to the application is then accessible via the API — it is up to the application to manage data access for its own users.
User accounts managed by Carmoove: authentication is done with the appId and appKey provided by Carmoove, plus the user's credentials (username and password). The data returned by the API then only concerns the vehicles this user has access to.

The token provided by the API must be sent in the header of every request, in the x-carmoove-token field. The Content-type field must also be sent in the header.

Once the token has expired, a new one can be requested without the user reconnecting, using the refresh_token provided at login. This refresh_token also has an expiration date; once it expires, the user must reconnect.

Obtaining a token¶

POST /v1/login
Content-type: application/json

{
  "appId": "your-app-id",
  "appKey": "your-app-key"
}

Parameters¶

Field	Type	Description
`appId`	String	Application ID, provided by Carmoove.
`appKey`	String	Authentication key, provided by Carmoove.
`username`	String	Username. Optional — only for a Carmoove-managed user account.
`password`	String	User password. Optional — only for a Carmoove-managed user account.

Response¶

Field	Type	Description
`token`	String	Authentication token, to provide in the `x-carmoove-token` header.
`until`	Timestamp	Date and time the token expires.
`refresh_token`	String	Token used to obtain a new authentication token.
`refresh_until`	Timestamp	Date and time the refresh token expires.
`update_password`	Boolean	Indicates whether the user must change their password.

Refreshing a token¶

Allows a new token to be issued once the old one has expired, without the user reconnecting, using the refresh_token.

POST /v1/refreshToken
Content-type: application/json

{
  "appId": "your-app-id",
  "appKey": "your-app-key",
  "refresh_token": "..."
}

Parameters¶

Field	Type	Description
`appId`	String	Application ID, provided by Carmoove.
`appKey`	String	Authentication key, provided by Carmoove.
`refresh_token`	String	Refresh token obtained at login.

Response¶

Field	Type	Description
`token`	String	Authentication token, to provide in the `x-carmoove-token` header.
`until`	Timestamp	Date and time the token expires.
`refresh_token`	String	New refresh token.
`refresh_until`	Timestamp	Date and time the new refresh token expires.

Changing the user password¶

Allows a logged-in user to change their password.

POST /v1/user/updatePassword
x-carmoove-token: <token>
Content-type: application/json

{
  "oldPassword": "...",
  "newPassword": "..."
}

Parameters¶

Field	Type	Description
`oldPassword`	String	Old password.
`newPassword`	String	New password (minimum 8 characters).

Response¶

Field	Type	Description
`error`	String	Error code. Absent on a successful request.

Errors¶

Error code	Description
`INVALID_OLD_PASSWORD`	The old password is incorrect.
`INVALID_PASSWORD_LENGTH`	The new password is too short.

Using the token¶

Any request to another API endpoint must include the obtained token, as well as the content type:

GET /v1/vehicles
x-carmoove-token: eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ2LXVSeWFuNUFCaE9NSXFaU0tjWG1STURrRHFx...
Content-type: application/json