Gerenciar chaves de API

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 sua experiência, como armazéns 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 autentique-se 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 suas experiências individuais e qualquer experiência de propriedade de grupo onde tenha o papel apropriado. Alguns escopos podem ser restringidos a experiências específicas, 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 grupo abaixo.

Para criar uma chave de API:

1. No Painel do Criador, vá até 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 recordar o propósito mais tarde, como PLACE_PUBLISHING_KEY para publicar lugares em sua experiência.

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 a experiência 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 todas as suas experiências de propriedade do usuário e a qualquer experiência de propriedade de grupo onde você tenha as permissões apropriadas, incluindo quaisquer experiências 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 a notação CIDR. Você pode encontrar o endereço IP de sua máquina local e adicioná-lo à seção Endereços IP Aceitos juntamente com endereços IP adicionais para aqueles que precisam de acesso. Se você não tiver um IP fixo, ou estiver utilizando a chave de API apenas em um ambiente local, você 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 da 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 grupo

Uma chave de API concede acesso a todos os recursos que a conta do usuário tem permissões, incluindo experiências 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 estã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 ser concedida 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 da 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 experiência, limite o acesso apenas às experiências específicas que são necessárias.

• Use restrições de endereço IP: Restringa o acesso à chave de API a endereços IP específicos ou a 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 do Roblox para garantir que sua chave possa ser usada com servidores do 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 período determinado, 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 andamento, pois sua automação pode falhar inesperadamente quando a chave expira.

• Use contas alternadas 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 grupo.

• Armazene chaves de API de forma segura: 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 Secrets Store.

• Não compartilhe chaves de API através de canais públicos: Nunca compartilhe chaves de API através de canais de comunicação pública, fóruns ou redes sociais. Compartilhe chaves apenas através de canais privados e seguros com membros de equipe confiáveis. Limite o acesso a quem você compartilha suas chaves para minimizar o raio de explosão 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 utilizando 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 da rede:

• Normal: 192.168.0.0
• CIDR: 192.168.0.0/24

A parte anterior é o endereço IP e a parte posterior é 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 é especialmente útil se você planeja executar suas aplicações em um servidor.

Status da chave de API

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 para um status ativo, consulte 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 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)

Exemplo de Solicitação de Introspecção da Chave de API
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 recursos.

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

Exemplo de Resposta de Introspecção da Chave de API
{
  "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"
}