Gerenciamento de API keys
Última atualização: 16 de julho de 2026
API keys são credenciais usadas para autenticar o SDK do PlayServ e as chamadas à REST API. Cada key tem escopo de um Project, de um tipo e de um Environment.
Um Project pode ter várias keys — para integrações diferentes, Environments diferentes ou fluxos de rotação. Usar uma key separada por integração facilita revogar o acesso com precisão, sem afetar serviços que não têm nada a ver com aquilo.
Tipos de key
O PlayServ tem dois tipos de key — Server e Client. Escolha aquele que corresponde ao lugar onde a key vai rodar.
Keys Server dão acesso total ao backend. Use-as a partir dos seus game servers, serviços de backend e pipelines de CI. Uma key Server pode chamar qualquer endpoint da REST API do PlayServ, inclusive os que alteram dados. Por isso, keys Server precisam ser mantidas em segredo e nunca podem ser incluídas em uma build de cliente nem distribuídas com o jogo.
Keys Client têm escopo limitado a um conjunto restrito de operações: publicação de Events e leitura do Catalog. Elas foram feitas para serem seguras dentro da build do seu jogo. Se uma key Client for extraída de uma build, o estrago é limitado — ela não permite modificar dados no servidor nem acessar nada além do que um cliente comum do jogo precisaria.
| Key Server | Key Client | |
|---|---|---|
| Acesso | Qualquer endpoint da REST API, inclusive escritas | Publicação de Events e leitura do Catalog |
| Use a partir de | Game servers, serviços de backend, CI | Builds do jogo distribuídas |
| Segura em uma build de cliente? | Não — nunca distribua | Sim, por design |
| Se for exposta | Acesso total ao backend do Project | Raio de impacto limitado |
Nunca distribua uma key Server em uma build de cliente. Uma key Server extraída do binário do jogo dá a um atacante acesso total ao backend do seu Project. Use uma key Client em qualquer coisa que chegue aos Players.
Trate todas as API keys como credenciais sensíveis. Não as compartilhe em tickets, capturas de tela, mensagens de chat, threads do Slack ou repositórios públicos.
Por que um Project pode ter várias keys
Um mesmo Project pode conter quantas keys forem necessárias. Isso é útil em várias situações comuns:
- Um serviço de backend e um pipeline de CI devem ter cada um a sua própria key Server, para que qualquer um dos dois possa ser rotacionado de forma independente, sem afetar o outro.
- Um cliente do jogo usa uma key Client. Um backend usa uma key Server. Eles nunca devem compartilhar a mesma credencial.
- Ao rotacionar uma key, ter uma segunda key permite emitir a nova credencial e atualizar o serviço antes de revogar a antiga — evitando indisponibilidade.
- Keys temporárias podem ser emitidas para prestadores de serviço, builds específicas ou integrações externas, e revogadas quando não forem mais necessárias.
Manter as keys separadas e bem nomeadas torna a tabela de keys muito mais fácil de administrar conforme o Project cresce.
Criar uma key
Abra a página Keys
Abra Keys na barra lateral do Project. Se ainda não houver nenhuma key, a página mostra um estado vazio com um botão Create your first key e um link Read the auth docs para consulta rápida.
Abra o formulário de criação
Clique em + Create key (ou em Create your first key) para abrir o formulário de criação.
Preencha os detalhes e crie
- Name — escolha um nome que descreva com clareza onde essa key é usada. Por exemplo:
dev-server-backend,dev-client-unity-build,ci-deploy-key. Um nome descritivo é a única forma de identificar uma key depois, na tabela. - Type — selecione Server ou Client conforme a integração. Veja Tipos de key acima se estiver em dúvida.
- Environment — selecione o Environment de destino. Atualmente Dev está disponível.
Clique em Create key. O token completo é exibido uma única vez — salve-o na hora (veja Salve o token abaixo).
Salve o token
Depois da criação, o valor completo do token é exibido exatamente uma vez, no diálogo Save your token.
Copie o token imediatamente e guarde-o em um lugar seguro — um gerenciador de senhas, um gerenciador de secrets ou uma variável de ambiente no seu sistema de CI. Clique em I've saved it, close para fechar o diálogo.
Esta é a única vez em que o token completo é mostrado. Depois que o diálogo é fechado, o secret não pode mais ser recuperado — apenas rotacionado. Se o token for perdido antes de ser salvo, você vai precisar rotacionar a key para obter um novo.
Lista de keys
Depois de fechar o diálogo, a key aparece na tabela Keys. Um Project com uma key Server e uma key Client fica assim:
A tabela mostra:
- Name — o rótulo que você atribuiu na criação
- Type · Env — o tipo da key (Server ou Client) e o Environment ao qual ela pertence
- Prefix — os primeiros caracteres da key, úteis para identificar qual secret está em uso sem expor o valor completo
- Key ID — um identificador estável da entrada, independente do valor do secret
- Status — quando a key foi usada pela última vez;
neversignifica que ela ainda não foi usada
Use os filtros Server, Client e Dev para reduzir a lista quando estiver lidando com muitas keys.
Renomear uma key
Para atualizar o nome de uma key, clique na linha correspondente na tabela. O campo de nome fica editável ali mesmo — digite um novo nome e pressione Enter para salvar.
Renomear não afeta o secret da key nem a sua capacidade de autenticar — só atualiza o rótulo na tabela.
Use isso para manter os nomes precisos conforme as integrações mudam com o tempo — por exemplo, renomeando dev-server-sdk-key para ci-deploy-server-key depois de reaproveitá-la em um pipeline de CI.
Rotacionar um secret
Rotacione uma key quando suspeitar que o secret atual foi exposto, ou como parte de uma política regular de rotação de credenciais. Rotacionar substitui o valor do secret mantendo a entrada da key — o key ID, o nome, o tipo e o Environment continuam os mesmos.
Abra o diálogo de rotação
Clique na linha de uma key e selecione Rotate secret. Um diálogo de confirmação aparece.
Confirme e salve o novo token
O secret atual para de autenticar imediatamente após a rotação. Qualquer serviço que ainda esteja usando o secret antigo vai falhar ao conectar. Atualize todos os serviços afetados com o novo secret antes de rotacionar, ou logo em seguida.
Clique em Rotate secret para confirmar. O novo token é exibido uma única vez, no mesmo diálogo Save your token — copie-o antes de fechar.
Revogar uma key
Revogue uma key para removê-la permanentemente do Project. É a ação correta quando a key não é mais necessária, quando o acesso de um prestador de serviço deve ser encerrado, ou quando a key foi comprometida e rotacionar não basta.
Abra o diálogo de revogação
Clique na linha de uma key e selecione Revoke key. Um diálogo de confirmação aparece.
Confirme a revogação
A key para de autenticar imediatamente após a revogação. Qualquer serviço que a esteja usando vai perder o acesso. Garanta que a key não está em uso antes de revogar, ou esteja pronto para atualizar os serviços afetados logo em seguida.
Clique em Revoke key para confirmar. Você tem uma janela de 10 segundos para desfazer a ação pela notificação toast ou pela linha da key, antes que ela seja removida em definitivo.
Boas práticas
- Use nomes descritivos. O nome é a única forma de entender para que serve uma key quando você revisar a tabela seis meses depois.
- Uma key por integração. Evite reutilizar a mesma key em serviços que não têm relação entre si. Se uma integração for comprometida, você vai querer poder revogar só aquela key.
- Nunca coloque keys Server em builds de cliente. Uma key Server extraída do binário do jogo dá a um atacante acesso total ao backend do seu Project.
- Rotacione ao suspeitar de exposição. Se você tiver qualquer motivo para achar que um secret foi visto por quem não deveria, rotacione na hora.
- Revogue keys não utilizadas. Keys que não estão mais em uso são risco desnecessário. Faça limpeza com regularidade.
Próximos passos
- Connecting a Project to Unity — configure o SDK com a sua nova key
- SDK Initialisation & Handshake — o que é cada entrada do SDK e de onde ela vem