API-Schlüssel verwalten

Open Cloud authentifiziert und autorisiert den API-Zugriff mit Hilfe von 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, wie z.B. Datenspeicher und Orte, hinzuzufügen.

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 seiner individuellen Spiele und aller gruppenbesessenen Spiele, für die er die entsprechende Rolle hat. Einige Bereiche können auf bestimmte Spiele beschränkt werden, aber nicht alle.

Für Details, wie man API-Schlüssel zur Verwaltung von Gruppenressourcen erstellt, 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 eindeutigen Namen für deinen API-Schlüssel ein. Verwende einen Namen, der dir hilft, den Zweck später zu erinnern, wie z.B. PLACE_PUBLISHING_KEY für das 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 deaktiviert, 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 Zukunft erstellst.

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

   Die meisten Operationen in der API-Referenz 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 Bereiche.

7. OPTIONAL

   Im Abschnitt Sicherheit kannst du den IP-Zugriff auf den Schlüssel explizit mit CIDR-Notation einschränken. Du kannst die IP-Adresse deines lokalen Computers finden und sie im Abschnitt Akzeptierte IP-Adressen zusammen mit zusätzlichen IP-Adressen für diejenigen hinzufügen, die Zugriff benötigen. Wenn du keine feste IP 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 die Verwendung deines API-Schlüssels zu ermöglichen.

8. OPTIONAL

   Um zusätzlichen Schutz für deine Ressourcen hinzuzufügen, setze ein Ablaufdatum für deinen Schlüssel.

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 des Creator Dashboards.

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 streng auf die Zielgruppe beschränkt ist. Dieses neue Konto, das für Automatisierungszwecke vorgesehen ist, sollte nur Zugriff auf die Zielgruppe erhalten und die minimalen Berechtigungen erhalten, die für seine Aufgabe erforderlich sind.

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 minimalen Berechtigungen zu, die für seine Aufgabe erforderlich sind (z.B. nur "Gruppenerfahrungen erstellen und bearbeiten").
4. Melde dich bei dem neuen Konto an und folge den Schritten 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 sensible Anmeldeinformationen, die sicher aufbewahrt werden sollten, um unbefugten Zugriff auf deine Daten zu verhindern. Hier sind einige Best Practices für die Verwaltung von API-Schlüsseln.

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

• Wähle die minimal erforderlichen Berechtigungen aus: Wähle beim Konfigurieren der Bereiche die minimal erforderlichen Berechtigungen für die beabsichtigte Verwendung des Schlüssels aus. Für die Bereiche, die es dir ermöglichen, den Zugriff nach Spiel einzuschränken, beschränke den Zugriff nur auf die spezifischen Spiele, die benötigt werden.

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

• Setze Ablaufdaten: Für kurzfristige Anwendungsfälle konfiguriere Ablaufdaten, um Schlüssel nach einem festgelegten Zeitraum automatisch zu deaktivieren, wodurch das Risiko verringert wird, falls ein Schlüssel kompromittiert wird. Das Setzen von Ablaufdaten wird für langfristige 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 zum Speichern und Steuern des Zugriffs auf deine Schlüssel. In Roblox-Orten verwende einen Secrets Store.

• 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 vertrauenswürdigen Teammitgliedern. Beschränke den Zugriff darauf, mit wem du deine Schlüssel teilst, um den Einflussbereich zu minimieren, falls ein Schlüssel kompromittiert wird.

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 mit normalen IP-Adressen oder unter Verwendung 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 Routing im Netzwerk 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 1-Bits im binären Format zählt. Im 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 zunächst einen aktiven Status, können jedoch im Laufe ihrer Lebensdauer inaktiv werden. Um zu erfahren, warum ein API-Schlüssel seinen Status geändert hat und wie du den API-Schlüssel wieder in den aktiven Status zurückversetzen kannst, siehe die folgende Tabelle.

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 Anfragenden verwendet werden kann und ob der Schlüssel oder der zuletzt generierte Benutzer moderiert ist.

Anfrage

(application/json)

curl --location --request POST 'https://apis.roblox.com/api-keys/v1/introspect' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key"
}'

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 mit dem Ziel Ersteller relevant. Der Identifikator universeDatastore ist nur für Bereiche mit dem Ziel universum-datastore relevant. Der Ressourcenidentifikator wird für Bereiche weggelassen, die keine Ressourcenauswahl unterstützen.

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

{
  "name": "test key",
  "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"
}