Authentifizierung

API-Schlüssel (hm_live_) als Bearer-Token senden: Schlüssel erstellen, Scopes und Ablauf wählen, rotieren, widerrufen – und was Auth-Fehler bedeuten.

Aktualisiert 18. Oktober 2026

Jede Anfrage an die HILLS API sendet einen API-Schlüssel im Header Authorization. Es gibt keine Sessions und keine Cookies: Die API ignoriert Cookies und sendet keine CORS-Header. Rufen Sie sie ausschließlich von Ihrem Server aus auf.

Der Schlüssel

Ein Schlüssel besteht aus hm_live_, gefolgt von 48 Hexadezimalzeichen. Es gibt nur eine Art von Schlüssel. Er liest und handelt für Ihr Kundenkonto und die Artists und Labels darunter.

Testschlüssel (hm_test_…) wurden am 12. Oktober 2026 eingestellt. Sie antworten mit 401 test_keys_retired. Um eine DDEX-Auslieferung zu testen, verwenden Sie denselben hm_live_-Schlüssel mit POST /ddex/validate oder den SFTP-Ordner /test. Beide legen nichts an. Siehe Testordner.

Schlüssel erstellen

Schlüssel erstellen Sie in der HILLS Web-App auf der Seite Developers (/dashboard/developers) mit New API key. Dafür müssen Sie Kontoinhaber sein oder eine Teamrolle mit der Berechtigung für API-Schlüssel haben. Die API ist Teil der Tarife Enterprise und Custom. In anderen Tarifen können Sie keine Schlüssel erstellen, und bestehende Schlüssel antworten mit 403 api_not_in_plan.

Für jeden Schlüssel legen Sie fest:

Einen Namen. Er sagt, wo der Schlüssel läuft, zum Beispiel ERP sync oder website.
Scopes. Was der Schlüssel darf. Siehe unten.
Ablauf. Eine Anzahl von Tagen oder keiner.

Der vollständige Schlüssel wird einmal angezeigt, beim Erstellen. Danach zeigen Listen nur noch sein Präfix (zum Beispiel hm_live_ab12cd34). Wenn Sie ihn verlieren, erstellen Sie einen neuen.

Schlüssel senden

Senden Sie ihn als Bearer-Token:

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

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 und GET /ping funktionieren mit jedem gültigen Schlüssel, unabhängig von seinen Scopes. Damit prüfen Sie einen Schlüssel. Siehe Konto.

Scopes

Jeder Schlüssel hat eigene Scopes. Ein Endpunkt, der einen Scope braucht, den der Schlüssel nicht hat, antwortet mit 403 insufficient_scope und nennt den fehlenden Scope in scope.

Scope	Was er erlaubt
`members:read`	Ihre Artists und Labels auflisten.
`members:write`	Neue Artists und Labels einladen.
`catalog:read`	Releases, Tracks und ihre Auslieferung an die Stores.
`earnings:read`	Erlöse nach Monat, Release oder Store.
`payouts:read`	Ihr Guthaben und Ihre Auszahlungsanfragen.
`links:read`	Smart Links und Pre-Saves mit ihren Statistiken.
`ddex:write`	DDEX-ERN-Batches liefern und ihren Status lesen. Erlaubt auch Tests.
`ddex:validate`	Nur DDEX-Batches testen. Es wird nichts angelegt.
`webhooks:read`	Webhook-Endpunkte und ihre Zustellungen auflisten.
`webhooks:write`	Webhook-Endpunkte, Secrets, Test-Events und Wiederholungen verwalten.

Neue Schlüssel starten mit den fünf Lese-Scopes: members:read, catalog:read, earnings:read, payouts:read und links:read. Die Schreib-, DDEX- und Webhook-Scopes sind nie voreingestellt.

Geben Sie jedem System einen eigenen Schlüssel mit genau den Scopes, die es braucht. Ein Reporting-Job braucht earnings:read, nicht ddex:write. Ein CI-Job, der DDEX-Dateien prüft, braucht nur ddex:validate.

Schlüssel rotieren

Ein Schlüssel lässt sich nicht an Ort und Stelle rotieren. So ersetzen Sie ihn ohne Ausfallzeit:

Erstellen Sie einen neuen Schlüssel mit denselben Scopes.
Spielen Sie ihn in Ihrem System ein.
Prüfen Sie, ob der Datenverkehr umgezogen ist. Die Schlüsselliste zeigt, wann jeder Schlüssel zuletzt verwendet wurde.
Widerrufen Sie den alten Schlüssel.

Schlüssel widerrufen

Öffnen Sie auf der Seite Developers das Menü des Schlüssels und wählen Sie Revoke. Er funktioniert sofort nicht mehr und antwortet mit 401 key_revoked. Widerrufen Sie einen Schlüssel umgehend, wenn er offengelegt wurde, etwa weil er in ein Repository committet oder in einen Chat kopiert wurde.

Jeder Schlüssel hat außerdem ein Anfrageprotokoll. Wählen Sie einen Schlüssel in der Liste aus, um seine letzten Anfragen zu sehen: Methode, Pfad, Status und Zeitpunkt. Anfragen werden 7 Tage aufbewahrt.

Auth-Fehler

Status	`code`	Was zu tun ist
401	`unauthenticated`	Kein Header `Authorization: Bearer`. Ergänzen Sie ihn.
401	`invalid_key`	Der Schlüssel existiert nicht oder ist falsch geschrieben. Prüfen Sie auf Leerzeichen oder einen abgeschnittenen Wert.
401	`key_revoked`	Der Schlüssel wurde widerrufen. Erstellen Sie einen neuen.
401	`key_expired`	Der Schlüssel ist abgelaufen. Erstellen Sie einen neuen.
401	`test_keys_retired`	Ein alter `hm_test_`-Schlüssel. Verwenden Sie einen `hm_live_`-Schlüssel.
403	`insufficient_scope`	Dem Schlüssel fehlt der in `scope` genannte Scope. Erstellen Sie einen Schlüssel mit diesem Scope.
403	`account_inactive`	Ihr Konto ist nicht aktiv. Wenden Sie sich an HILLS Music.
403	`api_not_in_plan`	Ihr Tarif enthält die API nicht. Sie ist Teil von Enterprise und Custom.

Alle Fehler haben dieselbe Form. Siehe Fehler.

Schlüssel sicher aufbewahren

Speichern Sie Schlüssel in einem Secret Manager oder in Umgebungsvariablen, nicht im Code.
Bauen Sie einen Schlüssel nie in eine Webseite, eine Mobile-App oder eine Desktop-App ein. Dort kann ihn jeder auslesen.
Verwenden Sie einen Schlüssel pro System. So können Sie einen widerrufen, ohne die anderen zu stoppen.
Setzen Sie bei kurzen Projekten und für externe Dienstleister ein Ablaufdatum.