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 a aplicação 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, em geral, ela pode acessar qualquer recurso para o qual o usuário tenha permissões, incluindo seus jogos individuais e qualquer jogo de propriedade de grupo 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 grupos, veja 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. Digite um nome exclusivo para sua chave de API. Use um nome que possa ajudar a recordar 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 qualquer jogo de propriedade de grupo onde você tenha as permissões apropriadas, incluindo qualquer jogo que você criar no futuro.

6. No menu suspenso 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 limpar armazenamento de memória requer a permissão universe.memory-store:flush.

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

7. (Opcional) Na seção Segurança, restrinja explicitamente o acesso por IP à chave usando notação CIDR. Você pode encontrar o endereço IP do seu computador local e adicioná-lo à seção Endereços IP Aceitos junto com endereços IP adicionais que precisam de acesso. Se você não tiver um IP fixo ou 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 e 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 da sua chave de API na página Extensões de 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 a criação de 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 as etapas 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 prevenir acesso não autorizado aos seus dados. Aqui estão algumas melhores práticas para gerenciar chaves de API.

• Crie chaves separadas para cada aplicação: Crie chaves de API separadas para cada aplicação 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 os 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 pode 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 as chaves após um determinado período, 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 as 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 os endereços IP que podem acessar a chave de API com 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 número 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 1 em formato binário. No exemplo anterior, 24 significa 255.255.255.0 (24 bits de 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 suas aplicações 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 da sua vida útil. Para saber porque uma chave de API mudou de status e como retornar a chave de API para um status ativo, veja a tabela a seguir.

Introspectar chaves de API

POST api-keys/v1/introspect

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

Requisiçã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 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"
}