# Authentification

> Envoyez votre clé d’API hm_live_ comme jeton Bearer : création, scopes, expiration, renouvellement, révocation et erreurs d’authentification.

Chaque requête à l’API HILLS envoie une clé d’API dans l’en-tête `Authorization`. Il n’y a ni session ni cookie : l’API ignore les cookies et n’envoie aucun en-tête CORS. Appelez-la uniquement depuis votre serveur.

## La clé

Une clé se compose de `hm_live_` suivi de 48 caractères hexadécimaux. Il n’existe qu’un seul type de clé. Elle lit et agit sur votre compte client ainsi que sur les artistes et labels qui lui sont rattachés.

Les clés de test (`hm_test_…`) ont été retirées le 12 octobre 2026. Elles renvoient `401 test_keys_retired`. Pour tester une livraison DDEX, utilisez la même clé `hm_live_` avec [POST /ddex/validate](https://developer.hillsmusic.com/fr/reference/ddex-deliveries/#test-a-ddex-message-or-batch), ou le dossier SFTP `/test`. Ni l’un ni l’autre ne crée quoi que ce soit. Voir [Dossier de test](https://developer.hillsmusic.com/fr/reference/test-folder/).

## Créer une clé

Les clés se créent dans l’application web HILLS, sur la page **Developers** (`/dashboard/developers`), avec **New API key**. Vous devez être le propriétaire du compte, ou avoir un rôle d’équipe disposant de la permission API keys. L’API est incluse dans les offres Enterprise et Custom. Sur les autres offres, vous ne pouvez pas créer de clés, et les clés existantes renvoient `403 api_not_in_plan`.

Pour chaque clé, vous choisissez :

- **Un nom.** Indiquez où elle est utilisée, par exemple `ERP sync` ou `website`.
- **Des scopes.** Ce que la clé a le droit de faire. Voir plus bas.
- **Une expiration.** Un nombre de jours, ou aucune.

La clé complète n’est affichée qu’une fois, à sa création. Ensuite, les listes n’en montrent que le préfixe (par exemple `hm_live_ab12cd34`). Si vous la perdez, créez-en une nouvelle.

## Envoyer la clé

Envoyez-la comme jeton Bearer :

```bash
curl "https://api.hillsmusic.com/v1/me" \
  -H "Authorization: Bearer $HILLS_API_KEY"
```

```js
const HILLS = "https://api.hillsmusic.com/v1";

export async function hills(path, init = {}) {
  const res = await fetch(HILLS + path, {
    ...init,
    headers: { ...init.headers, Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
  });
  const body = await res.json();
  if (!res.ok) throw Object.assign(new Error(body.error), { status: res.status, code: body.code });
  return body;
}

console.log(await hills("/me"));
```

`GET /me` et `GET /ping` acceptent toute clé valide, quels que soient ses scopes. Servez-vous-en pour vérifier une clé. Voir [Compte](https://developer.hillsmusic.com/fr/reference/account/).

## Scopes

Chaque clé a ses propres scopes, c’est-à-dire ses droits d’accès. Un endpoint qui exige un scope absent de la clé renvoie `403 insufficient_scope`, avec le scope manquant dans `scope`.

| Scope | Ce qu’il autorise |
| --- | --- |
| `members:read` | Lister vos artistes et labels. |
| `members:write` | Inviter de nouveaux artistes et labels. |
| `catalog:read` | Sorties, titres et leur livraison aux plateformes. |
| `earnings:read` | Revenus par mois, par sortie ou par plateforme. |
| `payouts:read` | Votre solde et vos demandes de retrait. |
| `links:read` | Smart links et pré-sauvegardes avec leurs statistiques. |
| `ddex:write` | Livrer des lots DDEX ERN et consulter leur statut. Permet aussi les tests. |
| `ddex:validate` | Tester des lots DDEX uniquement. Rien n’est créé. |
| `webhooks:read` | Lister les endpoints webhook et leurs livraisons. |
| `webhooks:write` | Gérer les endpoints webhook, les secrets, les événements de test et les nouvelles tentatives. |

Les nouvelles clés démarrent avec les cinq scopes de lecture : `members:read`, `catalog:read`, `earnings:read`, `payouts:read` et `links:read`. Les scopes d’écriture, DDEX et webhook ne sont jamais activés par défaut.

Donnez à chaque système sa propre clé, avec uniquement les scopes dont il a besoin. Un traitement de reporting a besoin de `earnings:read`, pas de `ddex:write`. Une tâche de CI qui vérifie des fichiers DDEX n’a besoin que de `ddex:validate`.

## Renouveler une clé

Une clé ne se renouvelle pas sur place. Pour la remplacer sans interruption de service :

1. Créez une nouvelle clé avec les mêmes scopes.
2. Déployez-la dans votre système.
3. Vérifiez que le trafic est passé sur la nouvelle clé. La liste des clés indique la date de dernière utilisation de chacune.
4. Révoquez l’ancienne clé.

## Révoquer une clé

Sur la page **Developers**, ouvrez le menu de la clé et choisissez **Revoke**. Elle cesse immédiatement de fonctionner et renvoie `401 key_revoked`. Révoquez sans attendre une clé qui a fuité, par exemple si elle a été commitée dans un dépôt ou collée dans une conversation.

Chaque clé a aussi un journal des requêtes. Sélectionnez une clé dans la liste pour voir ses requêtes récentes : méthode, chemin, statut et heure. Les requêtes sont conservées 7 jours.

## Erreurs d’authentification

| Statut | `code` | Que faire |
| --- | --- | --- |
| 401 | `unauthenticated` | Aucun en-tête `Authorization: Bearer`. Ajoutez-le. |
| 401 | `invalid_key` | La clé n’existe pas ou est mal saisie. Vérifiez l’absence d’espaces ou de valeur tronquée. |
| 401 | `key_revoked` | La clé a été révoquée. Créez-en une nouvelle. |
| 401 | `key_expired` | La clé a dépassé sa date d’expiration. Créez-en une nouvelle. |
| 401 | `test_keys_retired` | Une ancienne clé `hm_test_`. Utilisez une clé `hm_live_`. |
| 403 | `insufficient_scope` | La clé n’a pas le scope indiqué dans `scope`. Créez une clé qui le possède. |
| 403 | `account_inactive` | Votre compte n’est pas actif. Contactez HILLS Music. |
| 403 | `api_not_in_plan` | Votre offre n’inclut pas l’API. Elle est incluse dans Enterprise et Custom. |

Toutes les erreurs ont la même forme. Voir [Erreurs](https://developer.hillsmusic.com/fr/guides/errors/).

## Protéger vos clés

- Stockez les clés dans un gestionnaire de secrets ou dans des variables d’environnement, pas dans le code.
- Ne placez jamais une clé dans une page web, une application mobile ou une application de bureau : n’importe qui peut l’y lire.
- Utilisez une clé par système, pour pouvoir en révoquer une sans arrêter les autres.
- Fixez une expiration aux clés destinées à des projets courts et à des prestataires.

Source: https://developer.hillsmusic.com/fr/guides/authentication/