# Créer et révoquer une clé d'API

Une clé d’API authentifie la CLI et l’API. Ce guide crée une clé, la range au bon endroit, puis la révoque.

**Résultat attendu** : une clé qui commence par `ah_`, visible dans la liste **Clés actives** de ton organisation, et révocable depuis la liste.

**Avant de commencer** : être admin ou propriétaire de l’organisation. Les membres ne voient pas l’onglet **Clés d’API**.

## Créer une clé

1. **Ouvre l'onglet Clés d'API**

   Dans ton organisation, ouvre **Clés d’API**, puis clique **Créer une clé**.

2. **Donne-lui un nom parlant**

   Choisis un nom qui dit où la clé sert, par exemple `Poste de Léa` ou `CI GitHub`. Il t’aidera à savoir quelle clé révoquer.

3. **Copie la clé tout de suite**

   La fenêtre **Nouvelle clé d’API** affiche la clé complète une seule fois. Clique **Copier la clé** et range-la dans un gestionnaire de mots de passe.

   Host ne garde qu’une empreinte de la clé. Si tu la perds, aucune copie n’est possible : crée une nouvelle clé et révoque l’ancienne.

   **Vérification** : la clé apparaît dans **Clés actives** avec son nom et la date de création.

## Choisir la bonne portée

| Sorte de clé       | Qui la crée                                  | Ce qu’elle peut faire                                            |
| ------------------ | -------------------------------------------- | ---------------------------------------------------------------- |
| Clé d’organisation | Un admin ou un propriétaire, dans la console | Tous les projets de l’organisation, et créer de nouveaux projets |
| Clé de projet      | L’app GitHub, à l’import d’un dépôt          | Un seul projet. Tout autre projet répond `404`                   |

Pour ton poste de développement, prends une clé d’organisation. Pour un dépôt, laisse l’app GitHub poser sa clé de projet.

> **Attention**
>
> Une clé d’organisation lit les variables non sensibles de tous les projets avec `vercel pull`. Ne la mets jamais dans un dépôt, ni dans du code envoyé au navigateur.

## Utiliser la clé

La CLI lit la clé dans la variable `VERCEL_TOKEN`, qui évite de l’écrire dans l’historique du shell :

```bash
export VERCEL_TOKEN=ah_…
vercel --api https://api.host.hgdc.ch deploy
```

Pour une requête HTTP, envoie-la dans l’en-tête `Authorization` :

```bash
curl https://api.host.hgdc.ch/v2/user \
  -H "Authorization: Bearer $VERCEL_TOKEN"
```

## Révoquer une clé

1. **Repère la clé**

   Dans **Clés actives**, regarde la date de **Dernière utilisation**. Une clé inutilisée depuis longtemps peut être révoquée sans risque.

2. **Révoque-la**

   Clique **Révoquer la clé**, puis confirme.

   **Vérification** : la clé disparaît de **Clés actives**. Une requête avec cette clé répond `403` avec le code `forbidden`.

Une clé cesse aussi de fonctionner quand la personne qui l’a créée quitte l’organisation dans Account. Une clé n’expire pas d’elle-même.

## Si ça ne marche pas

- La CLI répond `403`, avec le message « Clé d’API absente ou invalide » : la clé est mal copiée, ou elle a été révoquée. Voir [Dépannage](/docs/guides/depannage/#la-cli-renvoie-403).
- Le message « Cette clé est limitée à un autre projet » apparaît : tu utilises la clé d’un dépôt pour un autre projet. Crée une clé d’organisation.

## Voir aussi

- [Clés d’API et sécurité](/docs/concepts/secrets-et-coffre/) : ce que Host garde et ce qu’il ne garde pas.
- [Référence de l’API](/docs/reference/api/introduction/#authentification) : l’en-tête, la portée et les limites.