API-Authentifizierung

API-Schlüssel

Jede API-Anfrage wird mit einem API-Schlüssel authentifiziert, der zu Ihrem Konto gehört. Schlüssel bestehen aus mk_live_, gefolgt von 32 Zeichen, und werden im Dashboard unter API keys erstellt.

Wir speichern nur einen SHA-256-Hash jedes Schlüssels, daher wird der vollständige Schlüssel nur einmal angezeigt: beim Erstellen. Wenn Sie einen Schlüssel verlieren, erstellen Sie einen neuen und widerrufen den alten. Je nach Tarif können Sie mehrere Schlüssel gleichzeitig besitzen. Ein eigener Schlüssel pro Anwendung oder Umgebung ist eine gute Gewohnheit.

Drei Wege, den Schlüssel zu senden

Übergeben Sie den Schlüssel so, wie es zu Ihrem HTTP-Client passt. Alle drei Varianten sind gleichwertig:

# 1. Query-Parameter
curl "https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY"

# 2. Authorization-Header (Bearer-Token)
curl "https://metalapi.com/api/v1/latest" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. X-API-Key-Header
curl "https://metalapi.com/api/v1/latest" \
  -H "X-API-Key: YOUR_API_KEY"

Verwenden Sie in der Produktion bevorzugt einen Header. Wir entfernen den Schlüssel aus dem Query-String, bevor wir unser Anfrageprotokoll schreiben, aber Ihre eigenen Logs, Proxys und Error-Tracker speichern unter Umständen die vollständige URL.

Ein fehlender Schlüssel führt zu Fehler 101, ein unbekannter oder widerrufener Schlüssel zu 102, beide mit HTTP-Status 401.

Domainbeschränkte Schlüssel

Wenn Sie die API aus clientseitigem JavaScript aufrufen, ist Ihr Schlüssel für jeden Besucher sichtbar. Falls sich das nicht vermeiden lässt, beschränken Sie den Schlüssel vorher im Dashboard auf Ihre eigenen Domains.

Ein beschränkter Schlüssel beantwortet nur Browser-Anfragen, deren Origin- (oder Referer-)Header zu einer der erlaubten Domains oder einer ihrer Subdomains passt. Anfragen von allen anderen Websites werden mit Fehler 107 (HTTP 403) abgelehnt und nicht berechnet.

Anfragen ohne Origin- oder Referer-Header, etwa Server-zu-Server-Aufrufe aus Ihrem Backend, Cronjobs oder Skripte, sind immer erlaubt. Ein beschränkter Schlüssel kann daher sowohl Ihre Website als auch Ihren Server bedienen. Mit example.com auf der Liste der erlaubten Domains:

# Erlaubt: Browser-Anfrage von einer Subdomain einer erlaubten Domain
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://shop.example.com"

# Abgelehnt mit 107: Origin steht nicht auf der Liste
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://another-site.com"

# Erlaubt: Server-zu-Server-Anfrage ohne Origin oder Referer
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY"

Schlüssel sicher aufbewahren

• Bewahren Sie Schlüssel auf dem Server auf und laden Sie sie aus Umgebungsvariablen oder einem Secrets-Manager. Committen Sie sie niemals in Git.
• Verwenden Sie für jede Anwendung und Umgebung einen eigenen Schlüssel, damit Sie einen davon widerrufen können, ohne die anderen anzutasten.
• Ist ein Schlüssel öffentlich geworden, erstellen Sie einen Ersatz, deployen ihn und widerrufen dann den alten Schlüssel im Dashboard.
• Rufen Sie die API immer über https:// auf.
• Auf öffentlichen Webseiten zeigt ein einbettbares Widget Live-Preise an, ohne dass ein Schlüssel in der Seite steht.

// Nur serverseitig: Der Schlüssel gelangt nie in den Browser
const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG", {
  headers: { "X-API-Key": process.env.METALAPI_KEY },
});