Authentification : obtenir un jeton (getToken)

Toutes les routes de l'API vMap (hormis celles qui créent un jeton) exigent un jeton d'authentification, transmis dans l'en-tête HTTP Authorization.

Ce jeton peut être obtenu de deux manières :

Cas d'usage	Méthode	Route	Élément à fournir
Connexion avec des identifiants	`POST`	`/vitis/privatetoken`	un login et un mot de passe dans le corps de la requête
Connexion via un jeton public	`GET`	`/vitis/privatetoken`	l'identifiant (`token_id`) d'un jeton de connexion dans l'en-tête `Authorization`

Note

Le jeton retourné est un jeton JWE chiffré. Sa durée de vie est déterminée par la propriété token_ttl du properties.json de Vitis (36000 secondes par défaut). Un jeton public, lui, porte la date limite définie à sa création, ou aucune si elle n'a pas été renseignée.

Obtenir un jeton avec des identifiants de connexion

POST /vitis/privatetoken

Cette route n'exige aucune authentification préalable (check_user est à false).

Paramètres du corps de la requête

Paramètre	Emplacement	Obligatoire	Description
`user`	corps de la requête	oui	login de l'utilisateur vMap
`password`	corps de la requête	oui	mot de passe de l'utilisateur

Le corps peut être transmis en application/x-www-form-urlencoded ou en application/json.

Exemple de requête

curl -X POST "https://[hostname]/vmap/v2/vitis/privatetoken" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "user=mon_login" \
     -d "password=mon_mot_de_passe"

Jeton retourné

{
  "status": 1,
  "data": {
    "login": "mon_login",
    "user_id": 12,
    "privileges": ["vmap_user", "vitis_user"],
    "change_password": false,
    "token": "eyJhbGciOiJ...",
    "exp": 1756900000000,
    "iat": 1756864000000
  }
}

token : jeton à réutiliser dans l'en-tête Authorization lors des appels suivants ;
exp / iat : dates d'expiration et de création, en millisecondes.

La date de dernière connexion de l'utilisateur est mise à jour et l'appel est tracé dans le journal CONNEXION_STATS.

Erreurs renvoyées

Code HTTP	`errorMessage`	Cause
401	`ERROR_INCORRECT_LOGIN_PASSWORD`	utilisateur inexistant, mot de passe erroné, ou utilisateur devant passer par la connexion OIDC
401	`ERROR_USER_IP_UNAUTHORIZED`	l'utilisateur possède une restriction d'IP qui n'autorise pas l'adresse appelante
501	`BAD_HASH_METHOD_FOR_DB_PASSWORD`	le mot de passe n'a pas pu être haché
503	`ERROR_EMPTY_TOKEN_PAYLOAD`	le jeton n'a pas pu être généré

Note

Les utilisateurs OIDC ne peuvent pas utiliser cette route : ils disposent de la route POST /vitis/oauthtoken, qui attend les paramètres code et state et n'est active que si la propriété allow_oauth2_connection vaut true.

Obtenir un jeton avec un jeton public

GET /vitis/privatetoken

Un jeton de connexion (aussi appelé jeton public) est créé depuis le mode Utilisateurs > Jetons de connexion de l'application, ou via la route POST /vitis/logintoken. Il permet de se connecter en tant que l'utilisateur associé, sans diffuser son mot de passe : c'est le mécanisme utilisé par les cartes publiques et les widgets.

En-tête attendu

Paramètre	Emplacement	Obligatoire	Description
`Authorization`	en-tête HTTP	oui	soit le `token_id` (UUID) d'un jeton de connexion, soit un jeton JWE déjà obtenu

L'identifiant token_id correspond à la colonne ID de la liste des jetons de connexion.

Exemple de requête avec un jeton public

curl -X GET "https://[hostname]/vmap/v2/vitis/privatetoken" \
     -H "Authorization: 3f2b8c1e-1c1a-4f0d-9c3a-2b7e5d6f8a90"

Informations retournées

{
  "status": 1,
  "data": {
    "privileges": ["vmap_user", "vitis_user"],
    "user": "mon_login",
    "user_id": 12,
    "validity_date": 1756900000,
    "token": "eyJhbGciOiJ..."
  }
}

token n'est présent que lorsque l'en-tête Authorization contenait un token_id : c'est le jeton JWE à utiliser pour les appels suivants ;
validity_date est la date d'expiration du jeton, en secondes ;
privileges liste les rôles de l'utilisateur, ce qui permet de savoir quelles routes lui sont accessibles.

Appelée avec un jeton JWE, la même route sert à vérifier la validité d'une session et à récupérer les rôles de l'utilisateur courant ; elle ne retourne alors pas le champ token.

Erreurs possibles

Code HTTP	`errorMessage`	Cause
401	`ERROR_MISSING_AUTHORIZATION_HEADER`	en-tête `Authorization` absent ou jeton introuvable en base
401	`ERROR_USER_IP_UNAUTHORIZED`	le jeton porte une restriction d'IP qui n'autorise pas l'adresse appelante
401	`ERROR_SESSION_EXPIRED`	jeton expiré ou payload non conforme

Utiliser le jeton

Le jeton obtenu se transmet tel quel, sans préfixe (Bearer n'est pas attendu) :

curl -X GET "https://[hostname]/vmap/v2/vmap/layers/42/query?limit=10" \
     -H "Authorization: eyJhbGciOiJ..."