Zarządzaj kluczami API

Open Cloud uwierzytelnia i autoryzuje dostęp do API za pomocą kluczy API, które pozwalają na dodanie szczegółowych uprawnień i kontroli bezpieczeństwa w celu uzyskania dostępu i wykorzystania określonych zasobów w twojej grze, takich jak magazyny danych i miejsca.

Wszystkie interfejsy API Open Cloud wymagają, abyś utworzył klucz API z ważnymi uprawnieniami i dołączył nagłówek x-api-key do swojego żądania, co pozwala aplikacji uwierzytelnić się w Open Cloud w twoim imieniu.

Tworzenie kluczy API

Możesz tworzyć i konfigurować klucze API, aby uzyskać dostęp do swoich zasobów. Dostęp klucza API jest określany przez uprawnienia użytkownika, który go posiada. Oznacza to, że może on ogólnie uzyskać dostęp do każdego zasobu, do którego użytkownik ma uprawnienia, w tym do swoich indywidualnych gier oraz wszelkich gier posiadanych przez grupę, w których ma odpowiednią rolę. Niektóre zakresy mogą być ograniczone do konkretnych gier, ale nie wszystkie.

Aby uzyskać szczegóły dotyczące tworzenia kluczy API do zarządzania zasobami grupy, zobacz sekcję Tworzenie kluczy API do zarządzania zasobami posiadanymi przez grupę poniżej.

Aby utworzyć klucz API:

1. W Panelu Twórcy przejdź do strony Klucze API.

2. Kliknij przycisk Utwórz klucz API.

3. Wprowadź unikalną nazwę dla swojego klucza API. Użyj nazwy, która pomoże ci przypomnieć sobie cel później, na przykład PLACE_PUBLISHING_KEY do publikowania miejsc w twojej grze.

4. W sekcji Uprawnienia dostępu wybierz API z menu Wybierz system API. Powtórz ten krok, jeśli musisz dodać wiele API do klucza.

5. Jeśli to możliwe, wybierz grę, do której chcesz uzyskać dostęp za pomocą klucza API.

   Opcjonalnie możesz wyłączyć Ogranicz według doświadczenia. Gdy jest wyłączone, twój klucz API ma dostęp do wszystkich gier posiadanych przez użytkownika oraz wszelkich gier posiadanych przez grupę, w których masz odpowiednie uprawnienia, w tym do wszelkich gier, które stworzysz w przyszłości.

6. Z rozwijanego menu Wybierz operacje wybierz operacje, które chcesz włączyć dla klucza API.

   Większość operacji w odniesieniu do API zawiera wymagane zakresy uprawnień. Na przykład operacja flush memory store wymaga uprawnienia universe.memory-store:flush.

   Aby uzyskać listę wszystkich zakresów i obsługiwanych przez nie interfejsów API, zobacz Zakresy.

7. OPCJONALNE

   W sekcji Bezpieczeństwo wyraźnie ogranicz dostęp IP do klucza, używając notacji CIDR. Możesz znaleźć adres IP swojego lokalnego komputera i dodać go do sekcji Akceptowane adresy IP wraz z dodatkowymi adresami IP dla tych, którzy potrzebują dostępu. Jeśli nie masz stałego adresu IP lub używasz klucza API tylko w lokalnym środowisku, możesz pozostawić przełącznik Ogranicz adresy IP niezaznaczony, aby umożliwić dowolnemu adresowi IP korzystanie z twojego klucza API.

8. OPCJONALNE

   Aby dodać dodatkową ochronę dla swoich zasobów, ustaw datę wygaśnięcia dla swojego klucza.

9. Kliknij przycisk Zapisz i wygeneruj klucz.

10. Skopiuj i zapisz ciąg klucza API w bezpiecznym miejscu, nie w publicznym repozytorium swojego kodu.

11. Sprawdź status swojego klucza API na stronie Rozszerzenia API w Panelu Twórcy.

Tworzenie kluczy API do zarządzania zasobami posiadanymi przez grupę

Klucz API zapewnia dostęp do wszystkich zasobów, do których konto użytkownika ma uprawnienia, w tym do gier osobistych poza grupą. Jeśli używasz klucza API swojego osobistego konta do automatyzacji grupy i ten klucz zostanie skompromitowany, inne zasoby, do których masz dostęp, również są narażone na ryzyko.

Aby temu zapobiec, zdecydowanie zalecamy utworzenie oddzielnego klucza API na dedykowanym alternatywnym koncie z dostępem ściśle ograniczonym do docelowej grupy. To nowe konto dedykowane do celów automatyzacji powinno mieć dostęp tylko do docelowej grupy i przyznane minimalne uprawnienia wymagane do wykonania jego zadania.

1. Utwórz nowe, dedykowane konto Roblox do swojej automatyzacji.
2. Zaproś nowe konto do swojej grupy.
3. Przypisz mu rolę grupową z minimalnymi uprawnieniami wymaganymi do wykonania jego zadania (np. tylko "Twórz i edytuj doświadczenia grupowe").
4. Zaloguj się na nowe konto i postępuj zgodnie z krokami w sekcji powyżej, aby utworzyć klucz API.
5. Użyj wygenerowanego klucza API do automatyzacji zasobów grupy.

Najlepsze praktyki w zarządzaniu kluczami API

Klucze API to wrażliwe dane uwierzytelniające, które powinny być przechowywane w bezpieczny sposób, aby zapobiec nieautoryzowanemu dostępowi do twoich danych. Oto kilka najlepszych praktyk w zarządzaniu kluczami API.

• Twórz oddzielne klucze dla każdej aplikacji: Twórz oddzielne klucze API dla każdej aplikacji lub przypadku użycia, aby izolować dostęp i zmniejszyć wpływ w przypadku skompromitowania klucza.

• Wybierz minimalne potrzebne uprawnienia: Podczas konfigurowania zakresów wybierz minimalne uprawnienia niezbędne do zamierzonego użycia klucza. Dla tych zakresów, które pozwalają na ograniczenie dostępu do zakresu według gry, ogranicz dostęp tylko do konkretnych gier, które są potrzebne.

• Używaj ograniczeń adresów IP: Ogranicz dostęp do klucza API do określonych adresów IP lub zakresów CIDR, aby zapobiec nieautoryzowanemu użyciu z nieznanych lokalizacji. Nie używaj ograniczeń adresów IP, gdy używasz swojego klucza API w miejscach Roblox, aby zapewnić, że twój klucz może być używany z serwerami Roblox.

• Ustaw daty wygaśnięcia: Dla krótkoterminowych przypadków użycia skonfiguruj daty wygaśnięcia, aby automatycznie dezaktywować klucze po określonym czasie, zmniejszając ryzyko w przypadku skompromitowania klucza. Ustawianie dat wygaśnięcia nie jest zalecane dla długoterminowych przypadków użycia, chyba że masz proces rotacji kluczy, ponieważ twoja automatyzacja może niespodziewanie zawieść, gdy klucz wygaśnie.

• Używaj dedykowanych alternatywnych kont do zarządzania zasobami grupy: Używaj dedykowanego konta z minimalnymi uprawnieniami do zarządzania zasobami grupy, jak szczegółowo opisano w sekcji Tworzenie kluczy API do zarządzania zasobami posiadanymi przez grupę.

• Przechowuj klucze API w bezpieczny sposób: Nigdy nie przechowuj kluczy API bezpośrednio w swoim kodzie źródłowym, systemach kontroli wersji ani skryptach, gdzie mogłyby być narażone. Użyj systemu zarządzania sekretami do przechowywania i kontrolowania dostępu do swoich kluczy. W miejscach Roblox użyj Sklepu z sekretami.

• Nie udostępniaj kluczy API przez publiczne kanały: Nigdy nie udostępniaj kluczy API przez publiczne kanały komunikacyjne, fora ani media społecznościowe. Udostępniaj klucze tylko przez bezpieczne, prywatne kanały z zaufanymi członkami zespołu. Ogranicz dostęp do osób, którym udostępniasz swoje klucze, aby zminimalizować ryzyko, jeśli klucz zostanie skompromitowany.

Format CIDR

Aby dodatkowo chronić swoje zasoby, podczas tworzenia klucza API określ adresy IP, które mogą uzyskać dostęp do klucza API, używając normalnych adresów IP lub używając notacji CIDR. Adres IP w formacie CIDR wygląda jak normalny adres IP, z tą różnicą, że kończy się ukośnikiem i liczbą dziesiętną, która reprezentuje, ile bitów adresu IP jest istotnych dla routingu sieciowego:

• Normalny: 192.168.0.0
• CIDR: 192.168.0.0/24

Pierwsza część to adres IP, a druga część to maska sieciowa, licząc bity 1 w formacie binarnym. W poprzednim przykładzie 24 oznacza 255.255.255.0 (24 jedynki), co pozwala na wszystkie adresy IP między 192.168.0.0 a 192.168.0.255. Zrozumienie formatu CIDR jest szczególnie przydatne, jeśli planujesz uruchomić swoje aplikacje na serwerze.

Status klucza API

Klucze API początkowo mają status aktywny, ale mogą stać się nieaktywne w trakcie swojego życia. Aby dowiedzieć się, dlaczego status klucza API się zmienił i jak przywrócić klucz API do statusu aktywnego, zobacz poniższą tabelę.

Introspekcja kluczy API

POST api-keys/v1/introspect

Pobierz informacje o kluczu API. Weryfikuje, czy klucz może być używany z adresu IP żądającego oraz czy klucz lub ostatni wygenerowany użytkownik jest moderowany.

Żądanie

(application/json)

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

Odpowiedź

Istnieją cztery możliwe identyfikatory zasobów, które mogą być obecne w każdym obiekcie zakresu:

• userId
• groupId
• universeId
• universeDatastore

Identyfikatory userId i groupId są istotne tylko dla zakresów z celem twórcy. Identyfikator universeDatastore jest istotny tylko dla zakresów z celem universe-datastore. Identyfikator zasobu zostanie pominięty dla zakresów, które nie obsługują wyboru zasobów.

Asterisk (*) w liście identyfikatorów zasobów wskazuje, że zakres ma uprawnienia do wszystkich zasobów tego typu.

{
  "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"
}