Jetons d'accès¶

Un jeton d'accès permet à un script ou à une application d'utiliser l'API REST en votre nom, sans votre mot de passe. Il ressemble à ceci :

iwal_xxxxxxxx

Un jeton commence par iwal_, suivi de 48 caractères hexadécimaux. Il s'envoie dans l'en-tête Authorization de chaque requête :

curl -H "Authorization: Bearer iwal_xxxxxxxx" https://my.yulpa.io/api/v2/me

Ce qu'il faut savoir¶

Un jeton agit avec vos droits : il voit et modifie ce que vous pouvez voir et modifier dans le manager iWal, ni plus ni moins.
Ses périmètres limitent ce qu'il peut faire (par exemple : lecture seule des factures).
Il peut avoir une date d'expiration.
Il n'est affiché qu'une seule fois, à sa création : YULPA n'en conserve qu'une empreinte et ne peut pas vous le communiquer à nouveau.
Il se crée et se révoque uniquement depuis votre session du manager : un jeton ne peut pas créer d'autre jeton.

Créer un jeton¶

La création d'un jeton se fait depuis la documentation interactive de l'API, en étant connecté au manager iWal dans le même navigateur.

Connectez-vous au manager iWal sur https://my.yulpa.io.
Dans le même navigateur, ouvrez la documentation interactive : https://my.yulpa.io/api/v2/docs.
Dépliez la section Compte, puis la route POST /v2/me/tokens (« Créer un jeton d'accès »).
Cliquez sur Try it out.
Remplissez le corps de la requête, par exemple :
```
{
  "name": "Supervision des services",
  "scopes": ["services:read", "billing:read"],
  "expires_at": "2027-12-31"
}
```
- name (obligatoire) : un nom qui vous permettra de reconnaître le jeton, 100 caractères au maximum ;
- scopes (facultatif) : la liste des périmètres accordés ; sans ce champ, le jeton a tous les périmètres (["*"]) ;
- expires_at (facultatif) : date d'expiration, au format AAAA-MM-JJ ou AAAA-MM-JJ HH:MM:SS, obligatoirement dans le futur ; sans ce champ, le jeton n'expire pas.
Cliquez sur Execute.
Dans la réponse (code 201), copiez immédiatement la valeur du champ token et rangez-la dans un endroit sûr (gestionnaire de mots de passe, coffre de secrets).

Exemple de réponse :

{
  "data": {
    "id": 42,
    "name": "Supervision des services",
    "prefix": "iwal_0123456",
    "scopes": ["services:read", "billing:read"],
    "created_at": "2026-11-14 10:12:00",
    "expires_at": "2027-12-31 00:00:00",
    "last_used_at": null,
    "last_ip": null,
    "revoked_at": null,
    "token": "iwal_xxxxxxxx"
  },
  "meta": {
    "warning": "Le jeton n'est affiché qu'une seule fois : conservez-le maintenant"
  }
}

Attention

Le jeton complet n'apparaît que dans cette réponse. Si vous le perdez, révoquez-le et créez-en un nouveau.

Note

La création d'un jeton est enregistrée dans le journal des actions de votre compte.

Périmètres¶

Les périmètres (scopes) restreignent un jeton : ils ne donnent jamais plus de droits que ceux de votre compte. Un périmètre se note <ressource>:read (lecture) ou <ressource>:write (modification). La valeur * accorde tous les périmètres.

Périmètre	Ce qu'il autorise
`me:read`	Lire son propre compte
`clients:read`	Lire les clients (titulaires)
`clients:write`	Créer et modifier les clients, archiver un client
`users:read`	Lire son compte utilisateur
`users:write`	Modifier son compte utilisateur
`rights:read`	Lire les délégations reçues et celles données sur ses clients et services
`rights:write`	Accepter, refuser ou quitter une délégation reçue ; accorder ou retirer une délégation
`billing:read`	Lire les bons de commande et factures (PDF compris) ; consulter les renouvellements, demander un devis, vérifier la disponibilité d'un domaine
`billing:write`	Référence comptable, abandon et validation sans paiement d'un bon de commande ; passer commande ; gérer les cartes de paiement
`tickets:read`	Lire les tickets de support et leurs pièces jointes
`tickets:write`	Ouvrir un ticket, répondre, fermer, rouvrir
`logs:read`	Lire les journaux : ses actions, mails et SMS
`hosting:read`	Lire la configuration technique des hébergements (web, DNS, MySQL, messagerie, fichiers…)
`hosting:write`	Modifier la configuration technique des hébergements (zones DNS, bases et utilisateurs MySQL, messagerie…)
`domains:read`	Lire les noms de domaine enregistrés (serveurs DNS, verrou, code de transfert si déverrouillé)
`domains:write`	Modifier les noms de domaine enregistrés chez le registrar : serveurs DNS, verrou de transfert
`containers:read`	Lire les conteneurs (état, historique des actions)
`containers:write`	Démarrer, arrêter, redémarrer un conteneur ; modifier sa description
`services:read`	Lire les services
`services:write`	Modifier les services : nom, renouvellement automatique, résiliation anticipée
`backups:read`	Lire les sauvegardes (snapshots) et restaurations
`backups:write`	Lancer une restauration depuis une sauvegarde

Le périmètre nécessaire à chaque route est indiqué dans la documentation interactive. Si le jeton n'a pas le bon périmètre, l'API répond 403 avec le message « Le jeton n'a pas le périmètre … ».

Astuce

Pour un script qui ne fait que consulter, accordez uniquement des périmètres :read. Par exemple, un outil de suivi des échéances n'a besoin que de services:read et billing:read.

Lister ses jetons¶

La route GET /v2/me/tokens (périmètre me:read) liste vos jetons, y compris ceux qui sont révoqués. Pour chaque jeton, elle indique son nom, ses premiers caractères (prefix), ses périmètres, ses dates de création, d'expiration et de révocation, ainsi que la date et l'adresse IP de sa dernière utilisation (last_used_at, last_ip). Le jeton complet n'est jamais renvoyé.

Elle peut être appelée depuis la documentation interactive (avec votre session) ou avec un jeton :

curl -H "Authorization: Bearer iwal_xxxxxxxx" https://my.yulpa.io/api/v2/me/tokens

Révoquer un jeton¶

Un jeton révoqué cesse immédiatement de fonctionner, et ne peut pas être réactivé.

Connectez-vous au manager iWal, puis ouvrez https://my.yulpa.io/api/v2/docs dans le même navigateur.
Avec la route GET /v2/me/tokens, repérez l'identifiant (id) du jeton à révoquer, grâce à son nom ou à son préfixe.
Dépliez la route DELETE /v2/me/tokens/{id}, cliquez sur Try it out, saisissez l'identifiant, puis cliquez sur Execute.
La réponse 204 confirme la révocation.

Un jeton révoqué reste visible dans la liste de vos jetons (champ revoked_at renseigné). La révocation est enregistrée dans le journal des actions de votre compte.

Note

Tous vos jetons sont révoqués automatiquement si votre compte n'est plus actif (mise en veille, suspension, résiliation). Si votre compte redevient actif, créez de nouveaux jetons.

Expiration¶

Un jeton créé avec une date d'expiration (expires_at) cesse de fonctionner à cette date : l'API répond alors 401 (« Jeton invalide, expiré ou révoqué »). Il n'est pas possible de prolonger un jeton : créez-en un nouveau avant l'échéance et remplacez-le dans vos outils.

Pare-feu du compte¶

Les jetons respectent le pare-feu de votre compte, comme la connexion au manager : si le pare-feu interdit la connexion au manager depuis une adresse IP, les appels à l'API depuis cette adresse sont refusés avec le code 401 et le message « Connexion interdite depuis cette adresse IP par le pare-feu du compte ».

Vous pouvez ainsi limiter l'usage de vos jetons aux seules adresses IP de vos serveurs, en autorisant la connexion uniquement depuis ces adresses.

Attention

Le pare-feu s'applique aussi à votre propre connexion au manager. Avant de restreindre les adresses autorisées, vérifiez que vous gardez un accès depuis votre poste (voir Pare-feu).

Bonnes pratiques¶

Un jeton par usage : créez un jeton distinct pour chaque script ou application, avec un nom explicite. Vous pourrez ainsi en révoquer un sans perturber les autres.
Le moins de périmètres possible : n'accordez que les périmètres réellement nécessaires, en lecture seule quand c'est possible.
Une date d'expiration : préférez des jetons qui expirent, et renouvelez-les régulièrement.
Ne jamais écrire le jeton dans le code : stockez-le dans une variable d'environnement ou un gestionnaire de secrets, et ne le publiez jamais dans un dépôt de code.
Restreindre les adresses IP avec le pare-feu du compte quand vos appels partent toujours des mêmes serveurs.
Surveiller l'utilisation : la liste de vos jetons indique la date et l'adresse IP de leur dernière utilisation. Une utilisation inattendue doit vous conduire à révoquer le jeton immédiatement.
Révoquer sans attendre un jeton qui a pu être exposé (fuite, départ d'un prestataire, poste perdu).