Erste Schritte

Authentifizierung

Jede Anfrage enthält Ihren API-Schlüssel. Er identifiziert Ihren Benutzer und legt fest, was die Antwort enthalten darf.

1Öffnen Sie im Kontrollzentrum Mein Konto › API und klicken Sie auf Schlüssel generieren. Geben Sie dem Schlüssel einen Namen, an dem Sie erkennen, wo er verwendet wird, z. B. „Monitoring“.
2Kopieren Sie den Schlüssel sofort: Aus Sicherheitsgründen wird er nur ein einziges Mal angezeigt. Wenn Sie ihn verlieren, widerrufen Sie ihn und generieren Sie einen neuen.
3Senden Sie den Schlüssel im Header X-API-Key oder als Authorization: Bearer.

Verwenden Sie den Schlüssel nur auf dem Server. Fügen Sie ihn niemals in Webseiten, Apps oder Links ein: Die API lehnt Schlüssel ab, die in der URL gesendet werden. Jeder Benutzer kann bis zu 10 aktive Schlüssel haben und jeden davon im selben Tab des Kontrollzentrums widerrufen.

Schlüsselformat

Der Schlüssel beginnt mit apk_, gefolgt von 48 Zeichen. Im Kontrollzentrum wird jeder Schlüssel nur mit seinem Anfang angezeigt, also mit demselben Wert wie im Feld api_key.prefix von /me.

Schlüssel widerrufen und austauschen

Wenn Sie einen Schlüssel widerrufen, werden Anfragen mit diesem Schlüssel sofort blockiert. Um einen Schlüssel ohne Unterbrechung Ihres Systems auszutauschen, generieren Sie zuerst den neuen, hinterlegen ihn auf Ihrem Server und widerrufen erst dann den alten.

Wenn Ihr System nur einen Teil der Daten benötigt, legen Sie im Kontrollzentrum einen eigenen Benutzer dafür an, nur mit den nötigen Berechtigungen, und generieren Sie den Schlüssel im Konto dieses Benutzers.

Was jeder Benutzer sehen kann

AnfragecURLPHPJavaScript

curl "https://api.on-cloud.live/v1/me" \
  -H "X-API-Key: $API_KEY"

<?php
$ch = curl_init('https://api.on-cloud.live/v1/me');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('API_KEY')],
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://api.on-cloud.live/v1/me', {
  headers: { 'X-API-Key': process.env.API_KEY }
});
const { data } = await res.json();

Mit dem Authorization-Header

curl "https://api.on-cloud.live/v1/me" \
  -H "Authorization: Bearer $API_KEY"

Fehlender oder widerrufener Schlüssel401

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid or has been revoked."
  }
}