API-Schlüssel und Authentifizierung

Senden Sie bei jeder Anfrage den Schlüssel als Bearer-Token im Header Authorization. Der Schlüssel gehört zu einer Organisation, die die API direkt daraus liest. Ein weiterer Header zur Angabe der Organisation ist daher nicht nötig; ein zusätzlich gesendeter Header X-ORGANIZATION-ID wird ignoriert.

curl --request GET \
  --url https://api.serverside.com/v1/baremetal \
  --header 'Authorization: Bearer <api-key>'

Die API liest den Schlüssel auch aus einem Header X-API-KEY, einem Alias für dieselben Zugangsdaten. Eine Anfrage enthält nur einen Berechtigungsnachweis: X-API-KEY zusammen mit Authorization oder ein doppelt gesendeter Header wird mit 400 abgelehnt (Authentifizierungsfehler).

Schlüssel erstellen

Der erste Schlüssel stammt aus der Cloud-Konsole: In den Einstellungen Ihrer Organisation bietet Manage API Keys die Schaltfläche Create an API Key. Sie fragt nach einem Namen und optional den Netzwerken, aus denen der Schlüssel funktionieren soll. Der fertige Schlüssel wird einmal angezeigt und kann nicht erneut angezeigt werden. Speichern Sie ihn daher sofort in einer Geheimnisverwaltung oder Umgebungsvariablen.

Ein Schlüssel besteht aus 63 Zeichen: org_, gefolgt von 59 Zeichen URL-sicherem Base64, die - und _ enthalten können. Nur ein mit org_ beginnender Bearer-Wert wird als API-Schlüssel gelesen. Jeder andere Wert gilt als Konsolensitzungstoken; ein ohne Präfix eingefügter Schlüssel schlägt daher mit 401 fehl.

Schlüssel werden ausschließlich in der Konsole verwaltet. Endpunkte zum Erstellen, Auflisten und Ändern von Schlüsseln erfordern eine angemeldete Konsolensitzung; ein Schlüssel kann daher keinen anderen erstellen, auflisten oder ändern.

Nicht mit einem Schlüssel aufrufbare Vorgänge

Die API-Referenz führt alle mit einem Schlüssel aufrufbaren Vorgänge auf. Die übrige API dient der Cloud-Konsole: eigene Organisationseinstellungen, Mitglieder, Einladungen, Rollen, API-Schlüssel, Benachrichtigungen, Benutzerprofil, Supporttickets sowie Länder- und Währungslisten. Jeder dieser Vorgänge antwortet einem Schlüssel mit 401 und diesem Body:

{
  "success": false,
  "data": null,
  "code": "UNAUTHENTICATED",
  "message": "This endpoint requires a signed-in user session. Organization API keys are not accepted here.",
  "traceId": "SRV-1A2B-3C4D-5E6F-7A8B"
}

Schlüsselberechtigungen

Ein neuer Schlüssel erhält alle Berechtigungen, die die integrierte Admin-Rolle am Tag seiner Erstellung hat. Deshalb bezeichnet die Konsole jeden Schlüssel mit Full Permissions. Diese Menge wird später nie aktualisiert. Eine später zur Plattform hinzugefügte Berechtigung fehlt älteren Schlüsseln; ein Endpunkt, der sie prüft, antwortet solchen Schlüsseln mit 403. Ein nach der Änderung erstellter Schlüssel besitzt sie.

Jede Endpunktseite nennt die vom Vorgang geprüfte Berechtigung, etwa organization.baremetal.deploy bei Betriebssystem bereitstellen. Sieben Vorgänge prüfen keine, und jeder Schlüssel der Organisation kann sie aufrufen: Listen und Einzelabfragen von Bare-Metal- und IP-Block-Tarifen, Regionen auflisten, Berechtigte Funktionen abrufen und SSH-Schlüssel auflisten. Alle anderen Vorgänge prüfen eine dieser Berechtigungen:

Schlüssel mit weniger Berechtigungen als die Admin-Rolle können nicht erstellt werden; ein neuer Schlüssel besitzt daher alle.

Schlüssel auf Ihre Netzwerke beschränken

Ein Schlüssel ohne erlaubte Netzwerke funktioniert von jeder Adresse aus. Sobald mindestens ein Netzwerk eingetragen ist, wird eine Anfrage von außerhalb aller erlaubten Netze wie ein falscher Schlüssel abgelehnt. Ein Eintrag ist eine einzelne Adresse (198.51.100.7) oder ein Netzwerk in CIDR-Form (198.51.100.0/24), IPv4 oder IPv6, und wird in der Konsole gesetzt; ein neuer Schlüssel akzeptiert bis zu 100 Einträge.

Die API vergleicht Netzwerke mit der von Cloudflare für die Verbindung gemeldeten Adresse. Erhält ein beschränkter Schlüssel im Anfrage-Playground eine 401, führen Sie dieselbe Anfrage mit cURL von einem erlaubten Rechner aus.

Schlüssel deaktivieren

Das Deaktivieren eines Schlüssels in der Konsole stoppt ihn, ohne seine Einstellungen zu verlieren; das Löschen entfernt ihn dauerhaft. Ein deaktivierter, gelöschter oder abgelaufener Schlüssel lässt jede Anfrage wie ein falscher Schlüssel fehlschlagen. Das Ablaufdatum ist vom Ein-/Ausschalter unabhängig; das Aktivieren eines abgelaufenen Schlüssels macht ihn daher nicht wieder nutzbar.

Authentifizierungsfehler

Ein auf beide Arten gesendeter Schlüssel erhält diese Antwort:

{
  "success": false,
  "data": null,
  "code": "VALIDATION_ERROR",
  "message": "X-API-KEY: Send one credential: the API key in the Authorization header or in X-API-KEY, not both.",
  "traceId": "SRV-1A2B-3C4D-5E6F-7A8B",
  "details": [
    {
      "code": "INVALID_VALUE",
      "message": "Send one credential: the API key in the Authorization header or in X-API-KEY, not both.",
      "field": "X-API-KEY",
      "location": "header"
    }
  ]
}

Beide 401-Antworten enthalten WWW-Authenticate-Header mit den vom Endpunkt akzeptierten Zugangsdaten: Bearer und ApiKey header="X-API-KEY", wo Schlüssel funktionieren; nur Bearer bei reinen Konsolenvorgängen, wo es für das Sitzungstoken der Konsole steht.

Die erste 401 nennt die konkrete Ursache nicht. Prüfen Sie in dieser Reihenfolge den Schlüssel selbst und ob er auf Bearer folgt, seinen Status unter Manage API Keys in der Konsole und anschließend seine erlaubten Netzwerke.