Jetons API¶

Toutes les routes de cette page sont publiques et authentifiées. Aucun privilège métier supplémentaire n'est contrôlé dans l'api, la liste authorizedApi du compte appelant reste appliquée lorsqu'elle est définie.

Les jetons API permettent à un utilisateur WebService de s'authentifier auprès de l'API REST de Maarch Courrier.

Accès et règles de gestion¶

L'utilisateur ciblé doit exister et être configuré avec le mode rest.
Un utilisateur ne peut posséder qu'un seul jeton valide.
La date d'expiration doit être postérieure à la date courante et ne peut pas dépasser un an.
Le paramètre id des routes correspond à l'identifiant technique users.id.
Lorsqu'une liste authorizedApi est définie sur le compte WebService, seules les routes qu'elle contient sont autorisées.

Le jeton obtenu doit être transmis dans l'en-tête Authorization :

Authorization: Bearer <token>

Warning

Le jeton donne accès aux routes autorisées pour le compte WebService. Il doit être conservé comme un secret et ne doit pas être écrit dans les journaux applicatifs.

Structure d'un jeton¶

Valeur	Type	Description
`creation_date`	string	Date de création au format `YYYY-MM-DD HH:MM:SS`
`token`	string	Jeton JWT à utiliser pour l'authentification
`expiration_date`	string	Date d'expiration au format `YYYY-MM-DD HH:MM:SS`
`last_used_date`	string ou `null`	Date de dernière utilisation au format `YYYY-MM-DD HH:MM:SS`

Créer un jeton API¶

Route¶

POST /rest/users/{id}/tokens

Paramètres¶

URL¶

Valeur	Type	Obligatoire	Description
`id`	integer	Oui	Identifiant technique de l'utilisateur WebService (`users.id`)

Body¶

Valeur	Type	Obligatoire	Description
`expirationDate`	string	Oui	Date d'expiration future, limitée à un an. Le format ISO 8601 est recommandé

Exemple¶

{
  "expirationDate": "2027-01-31T23:59:59+01:00"
}

Retour¶

Code HTTP	Type	Description
`200`	object	Le jeton a été créé
`400`	object	Paramètre invalide, utilisateur inexistant ou non WebService, date d'expiration hors limites ou jeton valide déjà présent
`401`	object	Authentification requise ou invalide
`403`	object	Route non autorisée pour le compte authentifié

Exemple¶

{
  "token": {
    "creation_date": "2026-07-27 10:15:00",
    "token": "<token>",
    "expiration_date": "2027-01-31 23:59:59",
    "last_used_date": null
  }
}

Erreurs métier¶

Situation	Code HTTP	Erreur
`id` absent ou invalide	`400`	`Route id is not set`
`expirationDate` absent	`400`	`Missing required fields`
Utilisateur inexistant	`400`	L'utilisateur n'existe pas
Utilisateur non configuré en mode `rest`	`400`	L'utilisateur n'est pas un utilisateur WebService
Date antérieure à la date courante	`400`	La date d'expiration doit être postérieure à la date du jour
Date supérieure à un an	`400`	La durée d'expiration du jeton ne peut dépasser un an
Jeton valide déjà présent	`400`	L'utilisateur a déjà un jeton valide

Récupérer un jeton API¶

Route¶

GET /rest/users/{id}/tokens

Paramètres¶

URL¶

Valeur	Type	Obligatoire	Description
`id`	integer	Oui	Identifiant technique de l'utilisateur (`users.id`)

Retour¶

Code HTTP	Type	Description
`200`	object	Le jeton de l'utilisateur a été récupéré
`400`	object	Identifiant invalide ou utilisateur inexistant
`401`	object	Authentification requise ou invalide
`403`	object	Route non autorisée pour le compte authentifié

Exemple avec un jeton¶

{
  "token": {
    "creation_date": "2026-07-27 10:15:00",
    "token": "<token>",
    "expiration_date": "2027-01-31 23:59:59",
    "last_used_date": "2026-08-04 08:42:17"
  }
}

Exemple sans jeton¶

La route renvoie un code 200 et un tableau vide dans la propriété token lorsque l'utilisateur ne possède aucun jeton :

{
  "token": []
}

Révoquer un jeton API¶

Route¶

DELETE /rest/users/{id}/tokens

Paramètres¶

URL¶

Valeur	Type	Obligatoire	Description
`id`	integer	Oui	Identifiant technique de l'utilisateur (`users.id`)

Retour¶

Code HTTP	Type	Description
`204`	aucun	Le jeton a été révoqué. La réponse ne contient pas de corps
`400`	object	Identifiant invalide, utilisateur inexistant ou jeton introuvable
`401`	object	Authentification requise ou invalide
`403`	object	Route non autorisée pour le compte authentifié

Après sa révocation, le jeton ne peut plus être utilisé pour s'authentifier.

Mettre à jour la date de dernière utilisation¶

Route¶

PUT /rest/users/{id}/tokens/lastUse

Paramètres¶

URL¶

Valeur	Type	Obligatoire	Description
`id`	integer	Oui	Identifiant technique de l'utilisateur (`users.id`)

Cette route ne reçoit pas de corps de requête. Elle remplace last_used_date par la date courante.

Retour¶

Code HTTP	Type	Description
`200`	object	La date de dernière utilisation a été mise à jour
`400`	object	Identifiant invalide, utilisateur inexistant ou jeton introuvable
`401`	object	Authentification requise ou invalide
`403`	object	Route non autorisée pour le compte authentifié

Exemple¶

{
  "token": {
    "creation_date": "2026-07-27 10:15:00",
    "token": "<token>",
    "expiration_date": "2027-01-31 23:59:59",
    "last_used_date": "2026-08-04 08:42:17"
  }
}

La date de dernière utilisation est également mise à jour automatiquement lorsqu'un jeton API est employé pour authentifier une requête.