Gérer les clés API

Open Cloud authentifie et autorise l'accès à l'API grâce à l'utilisation de clés API, qui vous permettent d'ajouter des autorisations granulaires et un contrôle de sécurité pour accéder et utiliser certaines ressources dans votre jeu, telles que les magasins de données et les lieux.

Toutes les API Open Cloud nécessitent que vous créiez une clé API avec des autorisations valides et que vous incluiez un en-tête x-api-key dans votre demande, ce qui permet à l'application de s'authentifier auprès d'Open Cloud en votre nom.

Créer des clés API

Vous pouvez créer et configurer des clés API pour accéder à vos ressources. L'accès d'une clé API est déterminé par les autorisations de l'utilisateur qui la possède. Cela signifie qu'elle peut généralement accéder à toute ressource pour laquelle l'utilisateur a des autorisations, y compris ses jeux individuels et tous les jeux appartenant à un groupe où il a le rôle approprié. Certains scopes peuvent être restreints à des jeux spécifiques, mais pas tous.

Pour des détails sur la façon de créer des clés API pour gérer les ressources de groupe, consultez la section Créer des clés API pour gérer les ressources appartenant à un groupe ci-dessous.

Pour créer une clé API :

1. Dans le Tableau de bord Créateur, allez à la page Clés API.

2. Cliquez sur le bouton Créer une clé API.

3. Entrez un nom unique pour votre clé API. Utilisez un nom qui peut vous aider à vous rappeler l'objectif plus tard, comme PLACE_PUBLISHING_KEY pour publier des lieux dans votre jeu.

4. Dans la section Autorisations d'accès, sélectionnez une API dans le menu Sélectionner le système API. Répétez cette étape si vous devez ajouter plusieurs API à la clé.

5. Si applicable, sélectionnez le jeu auquel vous souhaitez accéder avec la clé API.

   Vous pouvez désactiver Restreindre par expérience. Lorsqu'il est désactivé, votre clé API a accès à tous vos jeux appartenant à l'utilisateur et à tous les jeux appartenant à un groupe où vous avez les autorisations appropriées, y compris tous les jeux que vous créez à l'avenir.

6. Dans le menu déroulant Sélectionner les opérations, sélectionnez les opérations que vous souhaitez activer pour la clé API.

   La plupart des opérations dans la référence API incluent les scopes d'autorisation requis. Par exemple, l'opération vider le magasin de mémoire nécessite l'autorisation universe.memory-store:flush.

   Pour une liste de tous les scopes et des API qu'ils prennent en charge, consultez Scopes.

7. OPTIONNEL

   Dans la section Sécurité, restreignez explicitement l'accès IP à la clé en utilisant la notation CIDR. Vous pouvez trouver l'adresse IP de votre machine locale et l'ajouter à la section Adresses IP acceptées avec d'autres adresses IP pour celles qui ont besoin d'accès. Si vous n'avez pas d'IP fixe, ou si vous utilisez la clé API uniquement dans un environnement local, vous pouvez laisser le commutateur Restreindre les adresses IP décoché pour permettre à n'importe quelle IP d'utiliser votre clé API.

8. OPTIONNEL

   Pour ajouter une protection supplémentaire à vos ressources, définissez une date d'expiration pour votre clé.

9. Cliquez sur le bouton Enregistrer et générer la clé.

10. Copiez et enregistrez la chaîne de la clé API dans un endroit sécurisé, pas dans un dépôt public pour votre code.

11. Vérifiez le statut de votre clé API sur la page Extensions API du Tableau de bord Créateur.

Créer des clés API pour gérer les ressources appartenant à un groupe

Une clé API accorde l'accès à toutes les ressources pour lesquelles le compte utilisateur a des autorisations, y compris les jeux personnels en dehors du groupe. Si vous utilisez la clé API de votre compte personnel pour l'automatisation de groupe et que cette clé est compromise, d'autres ressources auxquelles vous avez accès sont également à risque.

Pour éviter cela, nous recommandons fortement de créer une clé API distincte sur un compte alternatif dédié avec un accès strictement limité au groupe cible. Ce nouveau compte dédié à des fins d'automatisation ne devrait avoir accès qu'au groupe cible et se voir accorder les autorisations minimales requises pour sa tâche.

1. Créez un nouveau compte Roblox dédié pour votre automatisation.
2. Invitez le nouveau compte dans votre groupe.
3. Assignez-lui un rôle de groupe avec les autorisations minimales requises pour sa tâche (par exemple, uniquement "Créer et modifier des expériences de groupe").
4. Connectez-vous au nouveau compte et suivez les étapes de la section ci-dessus pour créer une clé API.
5. Utilisez la clé API générée pour l'automatisation des ressources de groupe.

Meilleures pratiques pour gérer les clés API

Les clés API sont des identifiants sensibles qui doivent être conservés en sécurité pour éviter un accès non autorisé à vos données. Voici quelques meilleures pratiques pour gérer les clés API.

• Créez des clés séparées pour chaque application : Créez des clés API séparées pour chaque application ou cas d'utilisation afin d'isoler l'accès et de réduire l'impact si une clé est compromise.

• Sélectionnez les autorisations minimales nécessaires : Lors de la configuration des scopes, sélectionnez les autorisations minimales nécessaires pour l'utilisation prévue de la clé. Pour les scopes qui vous permettent de restreindre l'accès par jeu, limitez l'accès uniquement aux jeux spécifiques qui sont nécessaires.

• Utilisez des restrictions d'adresse IP : Restreignez l'accès à la clé API à des adresses IP spécifiques ou à des plages CIDR pour éviter une utilisation non autorisée depuis des emplacements inconnus. Ne pas utiliser de restrictions d'adresse IP lors de l'utilisation de votre clé API dans des lieux Roblox pour garantir que votre clé peut être utilisée avec les serveurs Roblox.

• Définissez des dates d'expiration : Pour des cas d'utilisation à court terme, configurez des dates d'expiration pour désactiver automatiquement les clés après une période définie, réduisant ainsi le risque si une clé est compromise. La définition de dates d'expiration n'est pas recommandée pour des cas d'utilisation à long terme, sauf si vous avez un processus de rotation des clés en place, car votre automatisation peut échouer de manière inattendue lorsque la clé expire.

• Utilisez des comptes alternatifs dédiés pour la gestion des ressources de groupe : Utilisez un compte dédié avec des autorisations minimales pour la gestion des ressources de groupe, comme détaillé dans la section Créer des clés API pour gérer les ressources appartenant à un groupe.

• Stockez les clés API en toute sécurité : Ne stockez jamais les clés API directement dans votre code source, vos systèmes de contrôle de version ou vos scripts où elles pourraient être exposées. Utilisez un système de gestion des secrets pour stocker et contrôler l'accès à vos clés. Dans les lieux Roblox, utilisez un Magasin de secrets.

• Ne partagez pas les clés API par des canaux publics : Ne partagez jamais les clés API par des canaux de communication publics, des forums ou des réseaux sociaux. Partagez uniquement les clés par des canaux privés et sécurisés avec des membres de l'équipe de confiance. Limitez l'accès à qui vous partagez vos clés pour minimiser le risque en cas de compromission d'une clé.

Format CIDR

Pour protéger davantage vos ressources, lors de la création d'une clé API, spécifiez les adresses IP qui peuvent accéder à la clé API en utilisant soit des adresses IP normales, soit en utilisant la notation CIDR. Une adresse IP CIDR ressemble à une adresse IP normale sauf qu'elle se termine par une barre oblique et un décimal qui représente combien de bits de l'adresse IP sont significatifs pour le routage réseau :

• Normal : 192.168.0.0
• CIDR : 192.168.0.0/24

La première partie est l'adresse IP et la dernière partie est le masque de réseau, comptant les bits de 1 en format binaire. Dans l'exemple précédent, 24 signifie 255.255.255.0 (24 1s) qui permet toutes les IP entre 192.168.0.0 et 192.168.0.255. Comprendre le format CIDR est particulièrement utile si vous prévoyez d'exécuter vos applications sur un serveur.

Statut de la clé API

Les clés API ont initialement un statut actif, mais elles peuvent devenir inactives au cours de leur durée de vie. Pour savoir pourquoi une clé API a changé de statut et comment ramener la clé API à un statut actif, consultez le tableau suivant.

Introspecter les clés API

POST api-keys/v1/introspect

Récupérez des informations sur une clé API. Vérifie si la clé peut être utilisée depuis l'adresse IP du demandeur et si la clé ou l'utilisateur généré en dernier est modéré.

Demande

(application/json)

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

Réponse

Il y a quatre identifiants de ressource possibles qui peuvent être présents dans chaque objet de scope :

• userId
• groupId
• universeId
• universeDatastore

Les identifiants userId et groupId ne sont pertinents que pour les scopes avec la cible créateur. L'identifiant universeDatastore n'est pertinent que pour les scopes avec la cible universe-datastore. L'identifiant de ressource sera omis pour les scopes qui ne prennent pas en charge la sélection de ressources.

Un astérisque (*) dans la liste des identifiants de ressource indique que le scope a l'autorisation sur toutes les ressources de ce type.

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