Gestionar claves API

Open Cloud autentica y autoriza el acceso a la API mediante el uso de claves API, que te permiten agregar permisos granulares y control de seguridad para acceder y utilizar ciertos recursos en tu juego, como almacenes de datos y lugares.

Todas las API de Open Cloud requieren que crees una clave API con permisos válidos e incluyas un encabezado x-api-key en tu solicitud, lo que permite a la aplicación autenticarse en Open Cloud en tu nombre.

Crear claves API

Puedes crear y configurar claves API para acceder a tus recursos. El acceso de una clave API está determinado por los permisos del usuario que la posee. Esto significa que generalmente puede acceder a cualquier recurso para el que el usuario tenga permisos, incluidos sus juegos individuales y cualquier juego de propiedad de grupo donde tenga el rol apropiado. Algunos ámbitos pueden restringirse a juegos específicos, pero no todos.

Para obtener detalles sobre cómo crear claves API para gestionar recursos de grupo, consulta la sección Crear claves API para gestionar recursos de propiedad de grupo a continuación.

Para crear una clave API:

1. En el Tablero del Creador, ve a la página Claves API.

2. Haz clic en el botón Crear clave API.

3. Ingresa un nombre único para tu clave API. Usa un nombre que te ayude a recordar el propósito más adelante, como PLACE_PUBLISHING_KEY para publicar lugares en tu juego.

4. En la sección Permisos de Acceso, selecciona una API del menú Seleccionar Sistema API. Repite este paso si necesitas agregar múltiples APIs a la clave.

5. Si es aplicable, selecciona el juego al que deseas acceder con la clave API.

   Opcionalmente, puedes desactivar Restringir por Experiencia. Cuando está desactivado, tu clave API tiene acceso a todos tus juegos de propiedad del usuario y a cualquier juego de propiedad de grupo donde tengas los permisos apropiados, incluidos los juegos que crees en el futuro.

6. En el menú desplegable Seleccionar Operaciones, selecciona las operaciones que deseas habilitar para la clave API.

   La mayoría de las operaciones en la referencia de API incluyen los ámbitos de permisos requeridos. Por ejemplo, la operación vaciar almacén de memoria requiere el permiso universe.memory-store:flush.

   Para obtener una lista de todos los ámbitos y las APIs que admiten, consulta Ámbitos.

7. OPCIONAL

   En la sección Seguridad, restringe explícitamente el acceso IP a la clave utilizando notación CIDR. Puedes encontrar la dirección IP de tu máquina local y agregarla a la sección Direcciones IP Aceptadas junto con direcciones IP adicionales para aquellos que necesiten acceso. Si no tienes una IP fija, o si estás utilizando la clave API solo en un entorno local, puedes dejar la opción Restringir direcciones IP sin marcar para permitir que cualquier IP use tu clave API.

8. OPCIONAL

   Para agregar protección adicional a tus recursos, establece una fecha de expiración para tu clave.

9. Haz clic en el botón Guardar y Generar clave.

10. Copia y guarda la cadena de la clave API en un lugar seguro, no en un repositorio público para tu código.

11. Verifica el estado de tu clave API en la página Extensiones API del Tablero del Creador.

Crear claves API para gestionar recursos de propiedad de grupo

Una clave API otorga acceso a todos los recursos para los que la cuenta de usuario tiene permisos, incluidos juegos personales fuera del grupo. Si utilizas la clave API de tu cuenta personal para la automatización de grupos y esa clave se ve comprometida, otros recursos a los que tienes acceso también están en riesgo.

Para prevenir esto, recomendamos encarecidamente crear una clave API separada en una cuenta alternativa dedicada con acceso estrictamente limitado al grupo objetivo. Esta nueva cuenta dedicada para fines de automatización solo debe tener acceso al grupo objetivo y otorgarse los permisos mínimos requeridos para su tarea.

1. Crea una nueva cuenta de Roblox dedicada para tu automatización.
2. Invita a la nueva cuenta a tu grupo.
3. Asigna un rol de grupo con los permisos mínimos requeridos para su tarea (por ejemplo, solo "Crear y editar experiencias de grupo").
4. Inicia sesión en la nueva cuenta y sigue los pasos en la sección anterior para crear una clave API.
5. Utiliza la clave API generada para la automatización de recursos de grupo.

Mejores Prácticas Para Gestionar Claves API

Las claves API son credenciales sensibles que deben mantenerse seguras para prevenir el acceso no autorizado a tus datos. Aquí hay algunas mejores prácticas para gestionar claves API.

• Crea claves separadas para cada aplicación: Crea claves API separadas para cada aplicación o caso de uso para aislar el acceso y reducir el impacto si una clave se ve comprometida.

• Selecciona los permisos mínimos necesarios: Al configurar los ámbitos, selecciona los permisos mínimos necesarios para el uso previsto de la clave. Para aquellos ámbitos que te permiten restringir el acceso por juego, limita el acceso solo a los juegos específicos que se necesitan.

• Utiliza restricciones de dirección IP: Restringe el acceso a la clave API a direcciones IP específicas o rangos CIDR para prevenir el uso no autorizado desde ubicaciones desconocidas. No utilices restricciones de dirección IP al usar tu clave API en lugares de Roblox para asegurarte de que tu clave pueda ser utilizada con los servidores de Roblox.

• Establece fechas de expiración: Para casos de uso a corto plazo, configura fechas de expiración para deshabilitar automáticamente las claves después de un período establecido, reduciendo el riesgo si una clave se ve comprometida. No se recomienda establecer fechas de expiración para casos de uso a largo plazo a menos que tengas un proceso de rotación de claves en su lugar, ya que tu automatización puede fallar inesperadamente cuando la clave expire.

• Utiliza cuentas alternativas dedicadas para la gestión de recursos de grupo: Utiliza una cuenta dedicada con permisos mínimos para la gestión de recursos de grupo, como se detalla en la sección Crear claves API para gestionar recursos de propiedad de grupo.

• Almacena las claves API de forma segura: Nunca almacenes claves API directamente en tu código fuente, sistemas de control de versiones o scripts donde puedan ser expuestas. Utiliza un sistema de gestión de secretos para almacenar y controlar el acceso a tus claves. En lugares de Roblox, utiliza un Almacén de Secretos.

• No compartas claves API a través de canales públicos: Nunca compartas claves API a través de canales de comunicación públicos, foros o redes sociales. Solo comparte claves a través de canales seguros y privados con miembros de confianza del equipo. Limita el acceso a quienes compartes tus claves para minimizar el radio de explosión si una clave se ve comprometida.

Formato CIDR

Para proteger aún más tus recursos, al crear una clave API, especifica direcciones IP que pueden acceder a la clave API utilizando direcciones IP normales o utilizando la notación CIDR. Una dirección IP CIDR se ve como una dirección IP normal, excepto que termina con una barra y un decimal que representa cuántos bits de la dirección IP son significativos para el enrutamiento de red:

• Normal: 192.168.0.0
• CIDR: 192.168.0.0/24

La primera parte es la dirección IP y la última parte es la máscara de red, contando los bits de 1 en formato binario. En el ejemplo anterior, 24 significa 255.255.255.0 (24 1s) que permite todas las IP entre 192.168.0.0 y 192.168.0.255. Comprender el formato CIDR es particularmente útil si planeas ejecutar tus aplicaciones en un servidor.

Estado de la clave API

Las claves API inicialmente tienen un estado activo, pero pueden volverse inactivas a lo largo de su vida útil. Para aprender por qué una clave API ha cambiado de estado y cómo devolver la clave API a un estado activo, consulta la siguiente tabla.

Inspeccionar claves API

POST api-keys/v1/introspect

Recupera información sobre una clave API. Verifica si la clave puede ser utilizada desde la dirección IP del solicitante y si la clave o el último usuario generado están moderados.

Solicitud

(application/json)

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

Respuesta

Hay cuatro identificadores de recursos posibles que pueden estar presentes en cada objeto de ámbito:

• userId
• groupId
• universeId
• universeDatastore

Los identificadores userId y groupId son solo relevantes para los ámbitos con el objetivo de creador. El identificador universeDatastore es solo relevante para los ámbitos con el objetivo universe-datastore. El identificador de recurso se omitirá para los ámbitos que no admiten la selección de recursos.

Un asterisco (*) en la lista de identificadores de recursos indica que el ámbito tiene permiso sobre todos los recursos de ese tipo.

{
  "name": "clave de prueba",
  "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"
}