Gestire le chiavi API

Open Cloud autentica e autorizza l'accesso alle API tramite l'uso di chiavi API, che ti consentono di aggiungere permessi granulari e controlli di sicurezza per accedere e utilizzare determinate risorse nel tuo gioco, come i data store e i luoghi.

Tutte le API di Open Cloud richiedono di creare una chiave API con permessi validi e includere un'intestazione x-api-key nella tua richiesta, che consente all'applicazione di autenticarsi su Open Cloud per tuo conto.

Creare chiavi API

Puoi creare e configurare chiavi API per accedere alle tue risorse. L'accesso di una chiave API è determinato dai permessi dell'utente che la possiede. Ciò significa che può generalmente accedere a qualsiasi risorsa per cui l'utente ha permessi, inclusi i propri giochi individuali e qualsiasi gioco di proprietà di un gruppo in cui ha il ruolo appropriato. Alcuni ambiti possono essere limitati a giochi specifici, ma non tutti.

Per dettagli su come creare chiavi API per gestire le risorse di gruppo, vedere la sezione Creare chiavi API per gestire risorse di proprietà di un gruppo qui sotto.

Per creare una chiave API:

1. Nel Creator Dashboard, vai alla pagina Chiavi API.

2. Fai clic sul pulsante Crea chiave API.

3. Inserisci un nome unico per la tua chiave API. Usa un nome che possa aiutarti a ricordare lo scopo in seguito, come PLACE_PUBLISHING_KEY per pubblicare luoghi nel tuo gioco.

4. Nella sezione Permessi di accesso, seleziona un'API dal menu Seleziona sistema API. Ripeti questo passaggio se hai bisogno di aggiungere più API alla chiave.

5. Se applicabile, seleziona il gioco a cui desideri accedere con la chiave API.

   Puoi disabilitare facoltativamente Limita per esperienza. Quando disabilitato, la tua chiave API ha accesso a tutti i tuoi giochi di proprietà dell'utente e a qualsiasi gioco di proprietà di un gruppo in cui hai i permessi appropriati, inclusi eventuali giochi che crei in futuro.

6. Dal menu a discesa Seleziona operazioni, seleziona le operazioni che desideri abilitare per la chiave API.

   La maggior parte delle operazioni nella documentazione API include gli ambiti di permesso richiesti. Ad esempio, l'operazione flush memory store richiede il permesso universe.memory-store:flush.

   Per un elenco di tutti gli ambiti e delle API che supportano, vedere Ambiti.

7. OPZIONALE

   Nella sezione Sicurezza, limita esplicitamente l'accesso IP alla chiave utilizzando la notazione CIDR. Puoi trovare l'indirizzo IP del tuo computer locale e aggiungerlo alla sezione Indirizzi IP accettati insieme ad altri indirizzi IP per coloro che necessitano di accesso. Se non hai un IP fisso, o stai utilizzando la chiave API solo in un ambiente locale, puoi lasciare disattivata l'opzione Limita indirizzi IP per consentire a qualsiasi IP di utilizzare la tua chiave API.

8. OPZIONALE

   Per aggiungere ulteriore protezione alle tue risorse, imposta una data di scadenza per la tua chiave.

9. Fai clic sul pulsante Salva e genera chiave.

10. Copia e salva la stringa della chiave API in un luogo sicuro, non in un repository pubblico per il tuo codice.

11. Verifica lo stato della tua chiave API nella pagina Estensioni API del Creator Dashboard.

Creare chiavi API per gestire risorse di proprietà di un gruppo

Una chiave API concede accesso a tutte le risorse per cui l'account utente ha permessi, inclusi giochi personali al di fuori del gruppo. Se utilizzi la chiave API del tuo account personale per l'automazione di gruppo e quella chiave viene compromessa, anche altre risorse a cui hai accesso sono a rischio.

Per prevenire ciò, raccomandiamo vivamente di creare una chiave API separata su un account alternativo dedicato con accesso rigorosamente limitato al gruppo target. Questo nuovo account dedicato per scopi di automazione dovrebbe avere accesso solo al gruppo target e ricevere i permessi minimi necessari per il suo compito.

1. Crea un nuovo account Roblox dedicato per la tua automazione.
2. Invita il nuovo account nel tuo gruppo.
3. Assegna un ruolo di gruppo con i permessi minimi richiesti per il suo compito (ad es., solo "Crea e modifica esperienze di gruppo").
4. Accedi al nuovo account e segui i passaggi nella sezione sopra per creare una chiave API.
5. Usa la chiave API generata per l'automazione delle risorse di gruppo.

Migliori pratiche per la gestione delle chiavi API

Le chiavi API sono credenziali sensibili che devono essere mantenute sicure per prevenire accessi non autorizzati ai tuoi dati. Ecco alcune migliori pratiche per la gestione delle chiavi API.

• Crea chiavi separate per ogni applicazione: Crea chiavi API separate per ogni applicazione o caso d'uso per isolare l'accesso e ridurre l'impatto se una chiave viene compromessa.

• Seleziona i permessi minimi necessari: Quando configuri gli ambiti, seleziona i permessi minimi necessari per l'uso previsto della chiave. Per quegli ambiti che ti consentono di limitare l'accesso per gioco, limita l'accesso solo ai giochi specifici necessari.

• Utilizza restrizioni sugli indirizzi IP: Limita l'accesso alla chiave API a indirizzi IP specifici o intervalli CIDR per prevenire utilizzi non autorizzati da posizioni sconosciute. Non utilizzare restrizioni sugli indirizzi IP quando utilizzi la tua chiave API nei luoghi Roblox per garantire che la tua chiave possa essere utilizzata con i server Roblox.

• Imposta date di scadenza: Per casi d'uso a breve termine, configura date di scadenza per disabilitare automaticamente le chiavi dopo un certo periodo, riducendo il rischio se una chiave viene compromessa. Impostare date di scadenza non è raccomandato per casi d'uso a lungo termine a meno che tu non abbia un processo di rotazione delle chiavi in atto, poiché la tua automazione può interrompersi inaspettatamente quando la chiave scade.

• Utilizza account alternativi dedicati per la gestione delle risorse di gruppo: Utilizza un account dedicato con permessi minimi per la gestione delle risorse di gruppo, come dettagliato nella sezione Creare chiavi API per gestire risorse di proprietà di un gruppo.

• Conserva le chiavi API in modo sicuro: Non conservare mai le chiavi API direttamente nel tuo codice sorgente, nei sistemi di controllo versione o negli script dove potrebbero essere esposte. Utilizza un sistema di gestione dei segreti per memorizzare e controllare l'accesso alle tue chiavi. Nei luoghi Roblox, utilizza un Secrets Store.

• Non condividere le chiavi API tramite canali pubblici: Non condividere mai le chiavi API tramite canali di comunicazione pubblici, forum o social media. Condividi le chiavi solo tramite canali privati e sicuri con membri fidati del team. Limita l'accesso a chi condividi le tue chiavi per ridurre al minimo il raggio d'azione se una chiave viene compromessa.

Formato CIDR

Per proteggere ulteriormente le tue risorse, quando crei una chiave API, specifica gli indirizzi IP che possono accedere alla chiave API utilizzando indirizzi IP normali o utilizzando la notazione CIDR. Un indirizzo IP CIDR appare come un normale indirizzo IP tranne che termina con una barra e un decimale che rappresenta quanti bit dell'indirizzo IP sono significativi per il routing di rete:

• Normale: 192.168.0.0
• CIDR: 192.168.0.0/24

La parte precedente è l'indirizzo IP e la parte successiva è la netmask, contando i bit di 1 in formato binario. Nell'esempio precedente, 24 significa 255.255.255.0 (24 1) che consente tutti gli IP tra 192.168.0.0 e 192.168.0.255. Comprendere il formato CIDR è particolarmente utile se prevedi di eseguire le tue applicazioni su un server.

Stato della chiave API

Le chiavi API inizialmente hanno uno stato attivo, ma possono diventare inattive nel corso della loro vita. Per scoprire perché una chiave API ha cambiato stato e come riportare la chiave API a uno stato attivo, vedere la tabella seguente.

Introspezione delle chiavi API

POST api-keys/v1/introspect

Recupera informazioni su una chiave API. Verifica se la chiave può essere utilizzata dall'indirizzo IP del richiedente e se la chiave o l'ultimo utente generato è moderato.

Richiesta

(application/json)

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

Risposta

Ci sono quattro possibili identificatori di risorsa che possono essere presenti in ciascun oggetto ambito:

• userId
• groupId
• universeId
• universeDatastore

Gli identificatori userId e groupId sono rilevanti solo per gli ambiti con il target creatore. L'identificatore universeDatastore è rilevante solo per gli ambiti con il target universe-datastore. L'identificatore di risorsa sarà omesso per gli ambiti che non supportano la selezione delle risorse.

Un asterisco (*) nell'elenco degli identificatori di risorsa indica che l'ambito ha permesso su tutte le risorse di quel tipo.

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