Gerenciar chaves de API

O Open Cloud autentica e autoriza o acesso à API com o uso de chaves de API, que permitem adicionar permissões granulares e controle de segurança para acessar e utilizar certos recursos em seu jogo, como armazenamentos de dados e lugares.

Todas as APIs do Open Cloud exigem que você crie uma chave de API com permissões válidas e inclua um cabeçalho x-api-key em sua solicitação, o que permite que o aplicativo se autentique no Open Cloud em seu nome.

Criar chaves de API

Você pode criar e configurar chaves de API para acessar seus recursos. O acesso de uma chave de API é determinado pelas permissões do usuário que a possui. Isso significa que ela pode geralmente acessar qualquer recurso para o qual o usuário tenha permissões, incluindo seus jogos individuais e quaisquer jogos de propriedade de grupos onde tenha o papel apropriado. Alguns escopos podem ser restritos a jogos específicos, mas nem todos.

Para detalhes sobre como criar chaves de API para gerenciar recursos de grupo, consulte a seção Criar chaves de API para gerenciar recursos de propriedade de grupos abaixo.

Para criar uma chave de API:

1. No Painel do Criador, vá para a página Chaves de API.

2. Clique no botão Criar Chave de API.

3. Insira um nome exclusivo para sua chave de API. Use um nome que possa ajudá-lo a lembrar o propósito mais tarde, como PLACE_PUBLISHING_KEY para publicar lugares em seu jogo.

4. Na seção Permissões de Acesso, selecione uma API no menu Selecionar Sistema de API. Repita esta etapa se precisar adicionar várias APIs à chave.

5. Se aplicável, selecione o jogo que você deseja acessar com a chave de API.

   Você pode opcionalmente desativar Restringir por Experiência. Quando desativado, sua chave de API tem acesso a todos os seus jogos de propriedade do usuário e a quaisquer jogos de propriedade de grupos onde você tenha as permissões apropriadas, incluindo quaisquer jogos que você criar no futuro.

6. No dropdown Selecionar Operações, selecione as operações que você deseja habilitar para a chave de API.

   A maioria das operações na referência da API inclui os escopos de permissão necessários. Por exemplo, a operação flush memory store requer a permissão universe.memory-store:flush.

   Para uma lista de todos os escopos e as APIs que eles suportam, consulte Escopos.

7. OPCIONAL

   Na seção Segurança, restrinja explicitamente o acesso IP à chave usando notação CIDR. Você pode encontrar o endereço IP de sua máquina local e adicioná-lo à seção Endereços IP Aceitos junto com endereços IP adicionais para aqueles que precisam de acesso. Se você não tiver um IP fixo, ou se estiver usando a chave de API apenas em um ambiente local, pode deixar a opção Restringir endereços IP desmarcada para permitir que qualquer IP use sua chave de API.

8. OPCIONAL

   Para adicionar proteção adicional aos seus recursos, defina uma data de expiração para sua chave.

9. Clique no botão Salvar & Gerar chave.

10. Copie e salve a string da chave de API em um local seguro, não em um repositório público para seu código.

11. Verifique o status de sua chave de API na página Extensões da API do Painel do Criador.

Criar chaves de API para gerenciar recursos de propriedade de grupos

Uma chave de API concede acesso a todos os recursos para os quais a conta do usuário tem permissões, incluindo jogos pessoais fora do grupo. Se você usar a chave de API da sua conta pessoal para automação de grupo e essa chave for comprometida, outros recursos aos quais você tem acesso também estarão em risco.

Para evitar isso, recomendamos fortemente criar uma chave de API separada em uma conta alternativa dedicada com acesso estritamente limitado ao grupo-alvo. Esta nova conta dedicada para fins de automação deve ter acesso apenas ao grupo-alvo e receber as permissões mínimas necessárias para sua tarefa.

1. Crie uma nova conta Roblox dedicada para sua automação.
2. Convide a nova conta para seu grupo.
3. Atribua a ela um papel de grupo com as permissões mínimas necessárias para sua tarefa (por exemplo, apenas "Criar e editar experiências de grupo").
4. Faça login na nova conta e siga os passos na seção acima para criar uma chave de API.
5. Use a chave de API gerada para automação de recursos de grupo.

Melhores Práticas para Gerenciar Chaves de API

As chaves de API são credenciais sensíveis que devem ser mantidas seguras para evitar acesso não autorizado aos seus dados. Aqui estão algumas melhores práticas para gerenciar chaves de API.

• Crie chaves separadas para cada aplicativo: Crie chaves de API separadas para cada aplicativo ou caso de uso para isolar o acesso e reduzir o impacto se uma chave for comprometida.

• Selecione as permissões mínimas necessárias: Ao configurar escopos, selecione as permissões mínimas necessárias para o uso pretendido da chave. Para aqueles escopos que permitem restringir o acesso por jogo, limite o acesso apenas aos jogos específicos que são necessários.

• Use restrições de endereço IP: Restringa o acesso à chave de API a endereços IP específicos ou intervalos CIDR para evitar uso não autorizado de locais desconhecidos. Não use restrições de endereço IP ao usar sua chave de API em lugares Roblox para garantir que sua chave possa ser usada com servidores Roblox.

• Defina datas de expiração: Para casos de uso de curto prazo, configure datas de expiração para desabilitar automaticamente chaves após um período definido, reduzindo o risco se uma chave for comprometida. Definir datas de expiração não é recomendado para casos de uso de longo prazo, a menos que você tenha um processo de rotação de chaves em vigor, pois sua automação pode falhar inesperadamente quando a chave expira.

• Use contas alternativas dedicadas para gerenciamento de recursos de grupo: Use uma conta dedicada com permissões mínimas para gerenciamento de recursos de grupo, conforme detalhado na seção Criar chaves de API para gerenciar recursos de propriedade de grupos.

• Armazene chaves de API com segurança: Nunca armazene chaves de API diretamente em seu código-fonte, sistemas de controle de versão ou scripts onde possam ser expostas. Use um sistema de gerenciamento de segredos para armazenar e controlar o acesso às suas chaves. Em lugares Roblox, use um Armazenamento de Segredos.

• Não compartilhe chaves de API por canais públicos: Nunca compartilhe chaves de API por canais de comunicação públicos, fóruns ou redes sociais. Compartilhe chaves apenas por canais seguros e privados com membros confiáveis da equipe. Limite o acesso a quem você compartilha suas chaves para minimizar o impacto se uma chave for comprometida.

Formato CIDR

Para proteger ainda mais seus recursos, ao criar uma chave de API, especifique endereços IP que podem acessar a chave de API, usando endereços IP normais ou usando a notação CIDR. Um endereço IP CIDR se parece com um endereço IP normal, exceto que termina com uma barra e um decimal que representa quantos bits do endereço IP são significativos para o roteamento de rede:

• Normal: 192.168.0.0
• CIDR: 192.168.0.0/24

A primeira parte é o endereço IP e a última parte é a máscara de rede, contando os bits de 1s em formato binário. No exemplo anterior, 24 significa 255.255.255.0 (24 1s) que permite todos os IPs entre 192.168.0.0 e 192.168.0.255. Compreender o formato CIDR é particularmente útil se você planeja executar seus aplicativos em um servidor.

Status da chave de API

As chaves de API inicialmente têm um status ativo, mas podem se tornar inativas ao longo de sua vida útil. Para saber por que uma chave de API mudou de status e como retornar a chave de API ao status ativo, consulte a tabela a seguir.

Introspecionar chaves de API

POST api-keys/v1/introspect

Recupere informações sobre uma chave de API. Verifica se a chave pode ser usada a partir do endereço IP do solicitante e se a chave ou o último usuário gerado está moderado.

Solicitação

(application/json)

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

Resposta

Existem quatro identificadores de recurso possíveis que podem estar presentes em cada objeto de escopo:

• userId
• groupId
• universeId
• universeDatastore

Os identificadores userId e groupId são relevantes apenas para escopos com o alvo de criador. O identificador universeDatastore é relevante apenas para escopos com o alvo universe-datastore. O identificador de recurso será omitido para escopos que não suportam seleção de recurso.

Um asterisco (*) na lista de identificadores de recurso indica que o escopo tem permissão em todos os recursos desse tipo.

{
  "name": "chave de teste",
  "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"
}