Gestire le chiavi API

Open Cloud autentica e autorizza l'accesso alle API con l'uso delle 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 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 a Open Cloud per tuo conto.

Creare chiavi API

Puoi creare e configurare chiavi API per accedere alle tue risorse. L'accesso a una chiave API è determinato dai permessi dell'utente che la possiede. Ciò significa che può generalmente accedere a qualsiasi risorsa per la quale l'utente ha permessi, comprese le proprie partite individuali e qualsiasi partita di proprietà di gruppo per 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, consulta la sezione Crea chiavi API per gestire risorse di proprietà di gruppo qui sotto.

Per creare una chiave API:

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

2. Clicca sul pulsante Crea Chiave API.

3. Inserisci un nome univoco per la tua chiave API. Usa un nome che ti aiuti a ricordare il 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 Restrizione per Esperienza. Quando disabilitata, la tua chiave API ha accesso a tutti i tuoi giochi di proprietà dell'utente e a qualsiasi gioco di proprietà del gruppo dove hai i permessi appropriati, comprese le partite che crei in futuro.

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

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

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

7. (Facoltativo) Nella sezione Sicurezza, limita esplicitamente l'accesso IP alla chiave utilizzando notazione CIDR. Puoi trovare l'indirizzo IP della tua macchina locale e aggiungerlo alla sezione Indirizzi IP Accettati insieme ad altri indirizzi IP per quelli che necessitano di accesso. Se non hai un IP fisso, o utilizzi la chiave API solo in un ambiente locale, puoi lasciare disattivato l'interruttore Restrizione indirizzi IP per consentire a qualsiasi IP di utilizzare la tua chiave API.

8. (Facoltativo): Per aggiungere ulteriore protezione per le tue risorse, imposta una data di scadenza per la tua chiave.

9. Clicca 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 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 è compromessa, anche altre risorse a cui hai accesso sono a rischio.

Per prevenire ciò, raccomandiamo fortemente di creare una chiave API separata su un account alternativo dedicato con accesso strettamente limitato al gruppo target. Questo nuovo account dedicato per scopi di automazione dovrebbe avere accesso solo al gruppo target e concedere 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 necessari per il suo compito (ad esempio, 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 gestire le chiavi API

Le chiavi API sono credenziali sensibili che dovrebbero essere mantenute sicure per prevenire accessi non autorizzati ai tuoi dati. Ecco alcune migliori pratiche per gestire le 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 consentono di limitare l'accesso all'ambito per gioco, limita l'accesso solo ai giochi specifici che sono necessari.

• Usa restrizioni sugli indirizzi IP: Limita l'accesso alla chiave API a indirizzi IP specifici o intervalli CIDR per prevenire l'uso non autorizzato da località sconosciute. Non utilizzare restrizioni sugli indirizzi IP quando usi 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 determinato periodo, riducendo il rischio se una chiave viene compromessa. Non è raccomandato impostare date di scadenza 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.

• Usa 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 descritto nella sezione Crea chiavi API per gestire risorse di proprietà di gruppo.

• Conserva le chiavi API in modo sicuro: Non conservare mai le chiavi API direttamente nel tuo codice sorgente, nei sistemi di controllo delle versioni, 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 sicuri e privati con membri fidati del team. Limita l'accesso a chi condividi le tue chiavi per ridurre il rischio in caso di compromissione di una chiave.

Formato CIDR

Per proteggere ulteriormente le tue risorse, quando crei una chiave API, specifica gli indirizzi IP che possono accedere alla chiave API sia utilizzando indirizzi IP normali che 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 prima parte è l'indirizzo IP e la parte successiva è il 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 tempo. Per capire 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)

Esempio di Richiesta Introspezione Chiave API
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 risorse che possono essere presenti in ciascun oggetto di ambito:

• userId
• groupId
• universeId
• universeDatastore

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

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

Esempio di Risposta Introspezione Chiave 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"
}