Zarządzaj kluczami API

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

Wszystkie interfejsy API Open Cloud wymagają od Ciebie stworzenia klucza API z ważnymi uprawnieniami oraz uwzględnienia nagłówka x-api-key w swoim żądaniu, 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 ogólnie może uzyskać dostęp do każdego zasobu, do którego użytkownik ma uprawnienia, w tym do swoich gier oraz do gier posiadanych przez grupę, w których ma odpowiednią rolę. Niektóre zasięgi mogą być ograniczone do konkretnych gier, ale nie wszystkie.

Aby uzyskać szczegółowe informacje na temat tego, jak tworzyć klucze API do zarządzania zasobami grupy, zapoznaj się z sekcją Tworzenie kluczy API do zarządzania zasobami będącymi własnością grupy poniżej.

Aby utworzyć klucz API:

1. W Kokpicie 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, np. PLACE_PUBLISHING_KEY w celu publikacji miejsc do twojej gry.

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

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

   Możesz opcjonalnie wyłączyć Ogranicz według doświadczenia. Po wyłączeniu twój klucz API ma dostęp do wszystkich gier będących własnością użytkownika oraz wszelkich gier będących własnością grupy, gdzie masz odpowiednie uprawnienia, w tym wszelkich gier, które tworzysz w przyszłości.

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

   Większość operacji w dokumencie referencyjnym API zawiera wymagane zasięgi uprawnień. Na przykład operacja flush memory store wymaga uprawnienia universe.memory-store:flush.

   Aby uzyskać listę wszystkich zasięgów i wspieranych przez nie interfejsów API, zobacz Zasięgi.

7. (Opcjonalnie) 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 Zaakceptowane 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 odznaczony, aby pozwolić dowolnemu adresowi IP używać twojego klucza API.

8. (Opcjonalnie): Aby dodać dodatkową ochronę dla swoich zasobów, ustaw datę wygaśnięcia 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. Zweryfikuj status swojego klucza API na stronie Rozszerzenia API w Kokpicie Twórcy.

Tworzenie kluczy API do zarządzania zasobami będącymi własnością grupy

Klucz API zapewnia dostęp do wszystkich zasobów, do których konto użytkownika ma uprawnienia, w tym do gier osobistych spoza grupy. 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ż będą zagrożone.

Aby temu zapobiec, zdecydowanie zalecamy utworzenie odrębnego 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 zadań.

1. Utwórz nowe, dedykowane konto Roblox do automatyzacji.
2. Zaproś nowe konto do swojej grupy.
3. Przypisz mu rolę grupową z minimalnymi wymaganymi uprawnieniami do wykonania 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 grupowych.

Najlepsze praktyki zarządzania kluczami API

Klucze API są poufnymi poświadczeniami, które należy przechowywać w bezpieczny sposób, aby zapobiec nieautoryzowanemu dostępowi do Twoich danych. Oto kilka najlepszych praktyk dotyczących zarządzania kluczami API.

• Twórz oddzielne klucze dla każdej aplikacji: Twórz oddzielne klucze API dla każdej aplikacji lub przypadku użycia, aby zisolować dostęp i zmniejszyć wpływ, jeśli klucz zostanie skomplikowany.

• Wybierz minimalne potrzebne uprawnienia: Podczas konfigurowania zasięgów wybierz minimalne uprawnienia niezbędne do zamierzonego wykorzystania klucza. W przypadku tych zasięgów, które umożliwiają ograniczenie dostępu do zakresu według gry, ogranicz dostęp tylko do konkretnych gier, które są potrzebne.

• Użyj 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: W przypadku krótkoterminowych przypadków użycia skonfiguruj daty wygaśnięcia, aby automatycznie dezaktywować klucze po określonym czasie, co zmniejsza ryzyko, jeśli klucz zostanie skompromitowany. Ustawianie dat wygaśnięcia nie jest zalecane w przypadku długoterminowych zastosowań, chyba że masz proces rotacji kluczy, ponieważ automatyzacja może niespodziewanie zawieść, gdy klucz wygasa.

• Używaj dedykowanych kont alternatywnych do zarządzania zasobami grupy: Użyj dedykowanego konta z minimalnymi uprawnieniami do zarządzania zasobami grupy, jak opisano w sekcji Tworzenie kluczy API do zarządzania zasobami będącymi własnością grupy.

• 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ć ujawnione. Użyj systemu zarządzania sekretami do przechowywania i kontrolowania dostępu do swoich kluczy. W miejscach Roblox używaj Secrets Store.

• Nie udostępniaj kluczy API poprzez publiczne kanały: Nigdy nie udostępniaj kluczy API za pośrednictwem publicznych kanałów komunikacyjnych, forów ani mediów społecznościowych. Udostępniaj klucze tylko przez bezpieczne, prywatne kanały z zaufanymi członkami zespołu. Ogranicz dostęp do osób, z którymi dzielisz swoje klucze, aby zminimalizować potencjalne ryzyko, jeśli klucz zostanie skomplikowany.

Format CIDR

Aby dalej chronić swoje zasoby, podczas tworzenia klucza API, wskaź IP adresy, które mogą uzyskać dostęp do klucza API, używając normalnych adresów IP lub notacji CIDR. Adres IP 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 rutowania w sieci:

• Normalny: 192.168.0.0
• CIDR: 192.168.0.0/24

Pierwsza część to adres IP, a druga część to maska sieciowa, liczona jako bity 1 w formacie binarnym. W poprzednim przykładzie 24 oznacza 255.255.255.0 (24 1s), co pozwala na wszelkie adresy IP pomię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 ciągu swojego życia. Aby dowiedzieć się, dlaczego klucz API zmienił status i jak przywrócić klucz API do statusu aktywnego, zapoznaj się z tablicą poniżej.

Introspekcja kluczy API

POST api-keys/v1/introspect

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

Żądanie

(application/json)

Przykładowe żądanie introspekcji klucza API
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 zasięgu:

• userId
• groupId
• universeId
• universeDatastore

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

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

Przykładowa odpowiedź introspekcji klucza API
{
  "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"
}