API-Schlüssel verwalten

Open Cloud authentifiziert und autorisiert den API-Zugriff mittels API-Schlüsseln, die es dir ermöglichen, granulare Berechtigungen und Sicherheitskontrollen für den Zugriff auf und die Nutzung bestimmter Ressourcen in deinem Spiel zu definieren, wie z. B. Datenspeicher und Orte.

Alle Open Cloud APIs erfordern, dass du einen API-Schlüssel mit gültigen Berechtigungen erstellst und einen x-api-key-Header in deiner Anfrage einfügst, der es der Anwendung ermöglicht, sich in deinem Namen bei Open Cloud zu authentifizieren.

API-Schlüssel erstellen

Du kannst API-Schlüssel erstellen und konfigurieren, um auf deine Ressourcen zuzugreifen. Der Zugriff eines API-Schlüssels wird durch die Berechtigungen des Benutzers bestimmt, der ihn besitzt. Das bedeutet, dass er im Allgemeinen auf jede Ressource zugreifen kann, für die der Benutzer Berechtigungen hat, einschließlich ihrer einzelnen Spiele und aller gruppenbesessenen Spiele, für die sie die entsprechende Rolle haben. Einige Bereiche können auf bestimmte Spiele beschränkt werden, aber nicht alle.

Für Details, wie du API-Schlüssel zur Verwaltung von Gruppenressourcen erstellen kannst, siehe den Abschnitt API-Schlüssel zur Verwaltung von gruppenbesessenen Ressourcen erstellen weiter unten.

Um einen API-Schlüssel zu erstellen:

1. Gehe im Creator Dashboard zur Seite API-Schlüssel.

2. Klicke auf die Schaltfläche API-Schlüssel erstellen.

3. Gib einen einzigartigen Namen für deinen API-Schlüssel ein. Verwende einen Namen, der dir hilft, den Zweck später zu erkennen, wie z. B. PLACE_PUBLISHING_KEY zum Veröffentlichen von Orten in deinem Spiel.

4. Wähle im Abschnitt Zugriffsberechtigungen eine API aus dem Menü API-System auswählen. Wiederhole diesen Schritt, wenn du mehrere APIs zum Schlüssel hinzufügen musst.

5. Wähle, falls zutreffend, das Spiel aus, auf das du mit dem API-Schlüssel zugreifen möchtest.

   Du kannst optional Einschränken nach Erfahrung deaktivieren. Wenn es deaktiviert ist, hat dein API-Schlüssel Zugriff auf alle deine benutzereigenen Spiele und alle gruppenbesessenen Spiele, für die du die entsprechenden Berechtigungen hast, einschließlich aller Spiele, die du in der Zukunft erstellst.

6. Wähle aus dem Dropdown Operationen auswählen die Operationen aus, die du für den API-Schlüssel aktivieren möchtest.

   Die meisten Operationen im API-Referenzdokument enthalten die erforderlichen Berechtigungsbereiche. Zum Beispiel erfordert die Operation Speicher leeren die Berechtigung universe.memory-store:flush.

   Für eine Liste aller Bereiche und der APIs, die sie unterstützen, siehe Berechtigungen.

7. (Optional) Im Abschnitt Sicherheit kannst du den IP-Zugriff auf den Schlüssel ausdrücklich mithilfe von CIDR-Notation einschränken. Du kannst die IP-Adresse deines lokalen Rechners finden und sie im Abschnitt Akzeptierte IP-Adressen zusammen mit zusätzlichen IP-Adressen hinzufügen, die Zugriff benötigen. Wenn du keine feste IP-Adresse hast oder den API-Schlüssel nur in einer lokalen Umgebung verwendest, kannst du den Schalter IP-Adressen einschränken deaktiviert lassen, um jeder IP zu erlauben, deinen API-Schlüssel zu verwenden.

8. (Optional): Um zusätzlichen Schutz für deine Ressourcen zu bieten, lege ein Ablaufdatum für deinen Schlüssel fest.

9. Klicke auf die Schaltfläche Speichern & Schlüssel generieren.

10. Kopiere und speichere die API-Schlüsselzeichenfolge an einem sicheren Ort, nicht in einem öffentlichen Repository für deinen Code.

11. Überprüfe den Status deines API-Schlüssels auf der Seite API-Erweiterungen im Creator Dashboard.

API-Schlüssel zur Verwaltung von gruppenbesessenen Ressourcen erstellen

Ein API-Schlüssel gewährt Zugriff auf alle Ressourcen, für die das Benutzerkonto Berechtigungen hat, einschließlich persönlicher Spiele außerhalb der Gruppe. Wenn du den API-Schlüssel deines persönlichen Kontos für die Gruppenautomatisierung verwendest und dieser Schlüssel kompromittiert wird, sind auch andere Ressourcen, auf die du Zugriff hast, gefährdet.

Um dies zu verhindern, empfehlen wir dringend, einen separaten API-Schlüssel auf einem dedizierten alternativen Konto zu erstellen, dessen Zugriff auf die Zielgruppe strikt beschränkt ist. Dieses neue Konto, das für Automatisierungszwecke vorgesehen ist, sollte nur Zugriff auf die Zielgruppe haben und die minimal erforderlichen Berechtigungen für seine Aufgabe erhalten.

1. Erstelle ein neues, dediziertes Roblox-Konto für deine Automatisierung.
2. Lade das neue Konto in deine Gruppe ein.
3. Weisen Sie ihm eine Gruppenrolle mit den minimal erforderlichen Berechtigungen für seine Aufgabe zu (z. B. nur „Gruppenerlebnisse erstellen und bearbeiten“).
4. Melde dich am neuen Konto an und befolge die Schritte im obigen Abschnitt, um einen API-Schlüssel zu erstellen.
5. Verwende den generierten API-Schlüssel für die Automatisierung von Gruppenressourcen.

Best Practices für die Verwaltung von API-Schlüsseln

API-Schlüssel sind sensitive Anmeldeinformationen, die sicher aufbewahrt werden sollten, um unbefugten Zugang zu deinen Daten zu verhindern. Hier sind einige bewährte Praktiken zur Verwaltung von API-Schlüsseln.

• Erstelle separate Schlüssel für jede Anwendung: Erstelle separate API-Schlüssel für jede Anwendung oder Verwendung, um den Zugriff zu isolieren und die Auswirkungen zu reduzieren, falls ein Schlüssel kompromittiert wird.

• Wähle die minimalen erforderlichen Berechtigungen: Wähle bei der Konfiguration von Berechtigungen die minimal erforderlichen Berechtigungen aus, die für die beabsichtigte Verwendung des Schlüssels notwendig sind. Für die Bereiche, die dir ermöglichen, den Zugriff nach Spiel einzuschränken, begrenze den Zugriff nur auf die spezifischen Spiele, die benötigt werden.

• Verwende IP-Adressen-Einschränkungen: Schränke den Zugriff auf den API-Schlüssel auf spezifische IP-Adressen oder CIDR-Bereiche ein, um unbefugte Nutzung von unbekannten Standorten zu verhindern. Verwende keine IP-Adressen-Einschränkungen, wenn du deinen API-Schlüssel in Roblox-Orten verwendest, um sicherzustellen, dass dein Schlüssel mit Roblox-Servern verwendet werden kann.

• Lege Ablaufdaten fest: Für kurzfristige Anwendungsfälle konfiguriere Ablaufdaten, um Schlüssel nach einem festgelegten Zeitraum automatisch zu deaktivieren, um das Risiko zu verringern, falls ein Schlüssel kompromittiert wird. Das Festlegen von Ablaufdaten wird für längerfristige Anwendungsfälle nicht empfohlen, es sei denn, du hast einen Schlüsselrotationsprozess implementiert, da deine Automatisierung unerwartet fehlschlagen kann, wenn der Schlüssel abläuft.

• Verwende dedizierte alternative Konten für die Verwaltung von Gruppenressourcen: Verwende ein dediziertes Konto mit minimalen Berechtigungen für die Verwaltung von Gruppenressourcen, wie im Abschnitt API-Schlüssel zur Verwaltung von gruppenbesessenen Ressourcen erstellen beschrieben.

• Speichere API-Schlüssel sicher: Speichere API-Schlüssel niemals direkt in deinem Quellcode, Versionskontrollsystemen oder Skripten, wo sie exponiert werden könnten. Verwende ein Geheimnisverwaltungssystem, um deine Schlüssel zu speichern und den Zugriff zu kontrollieren. In Roblox-Orten verwende einen Geheimnis-Speicher.

• Teile API-Schlüssel nicht über öffentliche Kanäle: Teile API-Schlüssel niemals über öffentliche Kommunikationskanäle, Foren oder soziale Medien. Teile Schlüssel nur über sichere, private Kanäle mit vertrauten Teammitgliedern. Begrenzt den Zugang zu den Personen, mit denen du deine Schlüssel teilst, um den Radius des Schadens im Falle einer Kompromittierung zu minimieren.

CIDR-Format

Um deine Ressourcen weiter zu schützen, gib beim Erstellen eines API-Schlüssels IP-Adressen an, die auf den API-Schlüssel zugreifen können, entweder durch normale IP-Adressen oder mithilfe der CIDR-Notation. Eine CIDR-IP-Adresse sieht aus wie eine normale IP-Adresse, endet jedoch mit einem Schrägstrich und einer Dezimalzahl, die angibt, wie viele Bits der IP-Adresse für das Netzwerk-Routing signifikant sind:

• Normal: 192.168.0.0
• CIDR: 192.168.0.0/24

Der erste Teil ist die IP-Adresse und der letzte Teil ist die Netzmaske, die die Anzahl der Einsen im Binärformat zählt. In dem vorherigen Beispiel bedeutet 24 255.255.255.0 (24 Einsen), was alle IPs zwischen 192.168.0.0 und 192.168.0.255 erlaubt. Das Verständnis des CIDR-Formats ist besonders nützlich, wenn du planst, deine Anwendungen auf einem Server auszuführen.

API-Schlüsselstatus

API-Schlüssel haben anfangs einen aktiven Status, können jedoch im Laufe ihrer Lebensdauer inaktiv werden. Um herauszufinden, warum sich der Status eines API-Schlüssels geändert hat und wie man den API-Schlüssel wieder in einen aktiven Status zurückversetzt, sieh dir die folgende Tabelle an.

API-Schlüssel introspektieren

POST api-keys/v1/introspect

Rufe Informationen über einen API-Schlüssel ab. Überprüft, ob der Schlüssel von der IP-Adresse des Anforderers verwendet werden kann und ob der Schlüssel oder der zuletzt generierte Benutzer moderiert ist.

Anfrage

(application/json)

Beispiel Introspekt API-Schlüssel Anfrage
curl --location --request POST 'https://apis.roblox.com/api-keys/v1/introspect' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "dein-api-schlüssel"
}'

Antwort

Es gibt vier mögliche Ressourcenidentifikatoren, die in jedem Bereichsobjekt vorhanden sein können:

• userId
• groupId
• universeId
• universeDatastore

Die Identifikatoren userId und groupId sind nur für Bereiche relevant, die das Ziel des Erstellers haben. Der Identifikator universeDatastore ist nur für Bereiche relevant, die das Ziel "universe-datastore" haben. Der Ressourcenidentifikator wird für Bereiche weggelassen, die die Auswahl von Ressourcen nicht unterstützen.

Ein Sternchen (*) in der Liste der Ressourcenidentifikatoren zeigt an, dass der Bereich Berechtigungen für alle Ressourcen dieses Typs hat.

Beispiel Introspekt API-Schlüssel Antwort
{
  "name": "Testschlüssel",
  "authorizedUserId": 234,
  "scopes": [
    {
      "name": "universe-datastores.objects",
      "operations": [
        "create"
      ],
      "universeDatastores": [
        {
          "universeId": "123",
          "datastoreName": "playerData"
        }
      ]
    },
    {
      "name": "asset",
      "operations": [
        "write"
      ],
      "groupIds": [
        "*"
      ],
      "userIds": [
        "*"
      ]
    }
  ],
  "enabled": true,
  "expired": false,
  "expirationTimeUtc": "2026-01-01T12:00:00.000Z"
}