Authentification¶

L'accès à l'API est sécurisé. Il est nécessaire de commencer par s'authentifier afin d'obtenir un token, qui sera obligatoire pour toute utilisation de l'API.

Il existe deux cas d'usage pour l'authentification :

Comptes utilisateurs gérés par l'application : les utilisateurs sont inconnus de Carmoove, seuls l'appId et l'appKey fournis par Carmoove sont nécessaires pour l'authentification. Toutes les données des véhicules liés à l'application sont alors accessibles via l'API — c'est à l'application de gérer les accès aux données pour ses propres utilisateurs.
Comptes utilisateur gérés par Carmoove : l'authentification se fait avec l'appId et l'appKey fournis par Carmoove, ainsi que les identifiants (username et password) de l'utilisateur. Les données remontées par l'API ne concernent alors que les véhicules auxquels cet utilisateur a accès.

Le token fourni par l'API doit être transmis dans l'en-tête de chaque requête, dans le champ x-carmoove-token. Il est également nécessaire de transmettre le champ Content-type dans l'en-tête.

Lorsque le token a expiré, il est possible d'en demander un nouveau sans reconnexion de l'utilisateur, à l'aide du refresh_token fourni lors de la connexion. Ce refresh_token possède également une date d'expiration ; une fois expiré, la reconnexion de l'utilisateur redevient obligatoire.

Obtenir un token¶

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

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

Paramètres¶

Champ	Type	Description
`appId`	String	Id d'application, fourni par Carmoove.
`appKey`	String	Clé d'authentification, fournie par Carmoove.
`username`	String	Nom d'utilisateur. Optionnel — uniquement pour un compte utilisateur géré par Carmoove.
`password`	String	Mot de passe utilisateur. Optionnel — uniquement pour un compte utilisateur géré par Carmoove.

Réponse¶

Champ	Type	Description
`token`	String	Token d'authentification, à fournir dans le header `x-carmoove-token`.
`until`	Timestamp	Date et heure de fin de validité du token.
`refresh_token`	String	Token permettant d'obtenir un nouveau token d'authentification.
`refresh_until`	Timestamp	Date et heure de fin de validité du refresh token.
`update_password`	Boolean	Indique si l'utilisateur doit modifier son mot de passe.

Rafraîchir un token¶

Permet de recevoir un nouveau token lorsque l'ancien est expiré, sans reconnexion de l'utilisateur, à partir du refresh_token.

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

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

Paramètres¶

Champ	Type	Description
`appId`	String	Id d'application, fourni par Carmoove.
`appKey`	String	Clé d'authentification, fournie par Carmoove.
`refresh_token`	String	Token de rafraîchissement obtenu lors de la connexion.

Réponse¶

Champ	Type	Description
`token`	String	Token d'authentification, à fournir dans le header `x-carmoove-token`.
`until`	Timestamp	Date et heure de fin de validité du token.
`refresh_token`	String	Nouveau token de rafraîchissement.
`refresh_until`	Timestamp	Date et heure de fin de validité du nouveau refresh token.

Modifier le mot de passe utilisateur¶

Permet à un utilisateur connecté de modifier son mot de passe.

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

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

Paramètres¶

Champ	Type	Description
`oldPassword`	String	Ancien mot de passe.
`newPassword`	String	Nouveau mot de passe (8 caractères minimum).

Réponse¶

Champ	Type	Description
`error`	String	Code d'erreur. Absent en cas de requête réussie.

Erreurs¶

Code d'erreur	Description
`INVALID_OLD_PASSWORD`	L'ancien mot de passe n'est pas correct.
`INVALID_PASSWORD_LENGTH`	Le nouveau mot de passe est trop court.

Utiliser le token¶

Toute requête vers un autre endpoint de l'API doit inclure le token obtenu, ainsi que le type de contenu :

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