Gérer les clés API

Open Cloud authentifie et autorise l'accès aux API grâce à des 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 de votre jeu, telles que les magasins de données et les lieux.

Toutes les API Open Cloud vous obligent à créer une clé API avec des autorisations valides et à inclure un en-tête x-api-key dans votre requête, 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 détenus par un groupe où il a le rôle approprié. Certains portées peuvent être restreintes à des jeux spécifiques, mais pas toutes.

Pour des détails sur la manière de créer des clés API pour gérer des ressources de groupe, voir la section Créer des clés API pour gérer les ressources détenues par 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 le but plus tard, tel que PLACE_PUBLISHING_KEY pour publier des lieux sur 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 que vous souhaitez accéder avec la clé API.

   Vous pouvez éventuellement désactiver Restreindre par expérience. Lorsqu'il est désactivé, votre clé API a accès à tous vos jeux détenus par l'utilisateur et à tous les jeux détenus par 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 des 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 portées d'autorisation requises. Par exemple, l'opération vider le magasin de mémoire nécessite la permission universe.memory-store:flush.

   Pour une liste de toutes les portées et des API qu'elles prennent en charge, consultez Portées.

7. (Optionnel) Dans la section Sécurité, restreindre 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 des adresses IP supplémentaires pour ceux 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 bouton 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 clé API dans un endroit sûr, pas dans un dépôt public pour votre code.

11. Vérifiez l'état de votre clé API sur la page Extensions API du Tableau de bord Créateur.

Créer des clés API pour gérer des ressources détenues par 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 en danger.

Pour prévenir cela, nous recommandons vivement 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 permissions 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 permissions minimales requises pour sa tâche (par exemple, seulement "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.

Bonnes pratiques pour la gestion des clés API

Les clés API sont des informations d'identification sensibles qui doivent être conservées en sécurité pour éviter tout accès non autorisé à vos données. Voici quelques bonnes pratiques pour gérer les clés API.

• Créer 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 permissions minimales nécessaires : Lors de la configuration des portées, sélectionnez les permissions minimales nécessaires pour l'utilisation prévue de la clé. Pour les portées 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 l'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é puisse ê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 certaine période, réduisant ainsi le risque en cas de compromission d'une clé. La définition de dates d'expiration n'est pas recommandée pour les cas d'utilisation à long terme, sauf si vous avez un processus de rotation de clés en place, car votre automatisation peut échouer de façon 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 permissions minimales pour la gestion des ressources de groupe, comme détaillé dans la section Créer des clés API pour gérer des ressources détenues par un groupe.

• Stockez les clés API en toute sécurité : Ne jamais stocker directement les clés API dans votre code source, systèmes de contrôle de version, ou 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 jamais partager les clés API par des canaux de communication publics, des forums ou des médias 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 afin de minimiser le périmètre de dommages 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 des adresses IP qui peuvent accéder à la clé API avec 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 un slash et une décimale 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 sous-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 IPs entre 192.168.0.0 et 192.168.0.255. Comprendre le format CIDR est particulièrement utile si vous prévoyez de faire fonctionner vos applications sur un serveur.

État de la clé API

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

Introspecter les clés API

POST api-keys/v1/introspect

Récupérer 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 dernièrement généré est modéré.

Demande

(application/json)

Exemple de demande d'introspection de clé API
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 portée :

• userId
• groupId
• universeId
• universeDatastore

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

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

Exemple de réponse d'introspection de clé API
{
  "name": "clé de test",
  "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"
}