Gestionar claves API

Open Cloud autentica y autoriza el acceso a la API mediante el uso de claves API, que te permiten añadir 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 y 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 se determina 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 propiedad de grupos donde tenga el rol apropiado. Algunos alcances pueden restringirse a juegos específicos, pero no todos.

Para obtener detalles sobre cómo crear claves API para gestionar recursos de grupos, consulta la sección Crear claves API para gestionar recursos de grupos más abajo.

Para crear una clave API:

1. En el Tablero del Creador, ve a la página de 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 añadir 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 usuario y cualquier juego 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 alcances de permisos requeridos. Por ejemplo, la operación vaciar almacenamiento de memoria requiere el permiso universe.memory-store:flush.

   Para una lista de todos los alcances y las APIs que soportan, consulta Alcances.

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 añadirla a la sección Direcciones IP Aceptadas junto con otras direcciones IP adicionales que necesiten acceso. Si no tienes una IP fija, o 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 añadir 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 de Extensiones de API del Tablero del Creador.

Crear claves API para gestionar recursos de grupos

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 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 alterna dedicada con acceso estrictamente limitado al grupo objetivo. Esta nueva cuenta, dedicada a fines de automatización, solo debería tener acceso al grupo objetivo y recibir los permisos mínimos necesarios 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. Asígnale un rol de grupo con los permisos mínimos necesarios para su tarea (por ejemplo, solo "Crear y editar experiencias grupales").
4. Inicia sesión en la nueva cuenta y sigue los pasos en la sección anterior para crear una clave API.
5. Usa la clave API generada para la automatización de recursos del 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í tienes 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 alcances, selecciona los permisos mínimos necesarios para el uso previsto de la clave. Para aquellos alcances que te permiten restringir el acceso por juego, limita el acceso solo a los juegos específicos que se necesitan.

• Usa restricciones de dirección IP: Restringe el acceso a la clave API a direcciones IP específicas o rangos CIDR para prevenir usos no autorizados desde ubicaciones desconocidas. No uses 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. Establecer fechas de expiración no se recomienda para casos de uso a largo plazo a menos que tengas un proceso de rotación de claves establecido, ya que tu automatización puede fallar inesperadamente cuando la clave expire.

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

• Almacena las claves API de manera segura: Nunca almacenes claves API directamente en tu código fuente, sistemas de control de versiones o scripts donde puedan ser expuestas. Usa un sistema de gestión de secretos para almacenar y controlar el acceso a tus claves. En lugares de Roblox, usa un Almacenamiento 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 las claves a través de canales seguros y privados con miembros del equipo de confianza. 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 puedan acceder a la clave API utilizando direcciones IP normales o usando la notación CIDR. Una dirección IP CIDR se parece a 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 1s en formato binario. En el ejemplo anterior, 24 significa 255.255.255.0 (24 1s) que permite todas las IPs entre 192.168.0.0 y 192.168.0.255. Entender el formato CIDR es especialmente útil si planeas ejecutar tus aplicaciones en un servidor.

Estado de la clave API

Las claves API tienen inicialmente un estado activo, pero pueden volverse inactivas durante su vida útil. Para saber por qué una clave API ha cambiado de estado y cómo devolverla 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)

Ejemplo de Solicitud de Inspección de Clave API
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 alcance:

• userId
• groupId
• universeId
• universeDatastore

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

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

Ejemplo de Respuesta de Inspección de Clave API
{
  "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"
}