Uma chave de API é uma credencial secreta que autentica requisições. Uma conta de serviço é uma identidade não humana que um aplicativo ou uma carga de trabalho automatizada pode usar. A conta de serviço pode ter suas próprias chaves de API. A conta e a chave, portanto, têm funções distintas na mesma configuração de autenticação.
Para seu trabalho de desenvolvimento, use uma chave de projeto que pertença à sua conta de usuário. Use uma conta de serviço para um aplicativo ou uma automação que precise de permissões e ciclo de vida próprios. Para gerenciar a organização, use uma chave de API de administração com as APIs de administração.
Escolha a identidade adequada
| Carga de trabalho | Identidade e credencial | Motivo |
|---|---|---|
| Desenvolvimento ou exploração que você faz localmente | Sua conta de usuário e uma chave de API do projeto | As requisições usam as suas permissões de acesso ao projeto. |
| Aplicativo implantado, tarefa agendada ou fluxo de trabalho de CI | Uma conta de serviço do projeto e sua chave de API | A carga de trabalho tem uma identidade independente da conta de cada desenvolvedor. |
| Carga de trabalho com um provedor de identidade compatível com a OpenAI | Uma conta de serviço do projeto com federação de identidades de cargas de trabalho | A carga de trabalho pode se autenticar sem armazenar uma chave de API de longa duração da OpenAI. |
| Automação que cria projetos ou gerencia as contas de serviço e as chaves desses projetos | Uma chave de API de administração | O gerenciamento da organização usa endpoints e permissões específicos para a administração. |
Uma chave que pertence a um usuário opera com as permissões de acesso desse usuário. Não compartilhe a chave de um desenvolvedor com a equipe nem use a identidade dessa pessoa como identidade permanente de um aplicativo em produção.
Cada conta de serviço pertence a um projeto. Conceda a cada carga de trabalho a identidade e o acesso de que ela precisa nesse projeto. Com projetos separados, você pode isolar os recursos, os membros e o uso de cada aplicativo ou ambiente. Com contas de serviço distintas no mesmo projeto, você pode diferenciar as cargas de trabalho sem criar outro projeto.
Entenda as permissões e os escopos
As permissões da chave de API e as de seu titular determinam o que a chave pode fazer. Os escopos podem restringir as operações permitidas pela chave, mas não concedem permissões que o usuário ou a conta de serviço não tenha. Mesmo uma chave sem restrições opera dentro dos limites das permissões efetivas de seu titular.
Atribua à conta de serviço apenas as funções necessárias para sua carga de trabalho. Em seguida, restrinja as chaves dessa conta quando apropriado. Consulte as permissões e funções para entender o modelo de autorização. Em contas de serviço com Terraform, você encontra uma configuração que cria uma identidade, atribui a ela uma função personalizada e emite uma chave com escopo definido.
Uma chave de API de administração tem uma finalidade diferente da chave que uma carga de trabalho usa no projeto. Mantenha a credencial administrativa no serviço confiável responsável por provisionar e gerenciar recursos. Para enviar requisições do aplicativo aos modelos, use a credencial da conta de serviço do projeto.
Automatize o gerenciamento de projetos e chaves
Se o seu aplicativo provisiona projetos para clientes, use uma conta de serviço do projeto para dar a cada carga de trabalho uma identidade independente do desenvolvedor que executa o provisionamento. Seu serviço de provisionamento usa as APIs de administração para gerenciar o projeto e as respectivas contas de serviço. O aplicativo provisionado usa sua própria credencial de projeto.
A tabela a seguir descreve as operações administrativas relevantes.
| Operação | Finalidade |
|---|---|
| Criar um projeto | Criar o projeto ao qual pertencerão os recursos e a conta de serviço da carga de trabalho. |
| Criar uma conta de serviço | Criar a identidade da carga de trabalho nesse projeto. A opção create_service_account_only cria a conta sem funções padrão e sem uma chave de API inicial. |
| Criar uma chave de API para uma conta de serviço | Emitir uma chave para uma conta de serviço existente, com escopos definidos e, quando necessário, uma data de expiração. |
| Gerenciar as chaves de API do projeto | Listar, consultar, atualizar ou revogar as chaves existentes do projeto, inclusive as das contas de serviço. |
Os endpoints de gerenciamento de chaves de API do projeto não permitem criar uma chave de projeto em nome de outro usuário para que ela pertença a ele. Para criar chaves programaticamente, use uma conta de serviço e o endpoint de criação de chaves dessa conta.
Criar uma conta de serviço sem funções padrão não concede à conta permissão para enviar requisições aos modelos. Atribua as permissões necessárias antes de usar as credenciais da conta. A criação de chaves também está sujeita às políticas de chaves da organização e do projeto, inclusive quando você usa uma conta de serviço.
Gerencie as credenciais ao longo do ciclo de vida
A API retorna o valor completo da chave de uma conta de serviço apenas no momento da criação da chave. Armazene a chave no seu gerenciador de segredos e disponibilize-a para a carga de trabalho no servidor. Não inclua chaves secretas em código executado no navegador, aplicativos móveis, sistemas de controle de versão, logs ou respostas enviadas aos clientes.
Defina uma data de expiração de acordo com as políticas da organização e do projeto. Para fazer a rotação de uma chave, emita uma nova chave, atualize a carga de trabalho para usá-la, verifique se a carga de trabalho funciona com a nova chave e revogue a anterior. A conta de serviço pode manter a mesma identidade mesmo quando suas chaves mudam.
Revise as permissões de acesso da carga de trabalho quando as responsabilidades dela mudarem. Ao desativar a carga de trabalho, revogue suas credenciais. Consulte as orientações sobre chaves de API em produção para saber mais sobre a governança das chaves e as políticas de expiração. Para autenticar uma carga de trabalho sem armazenar uma chave de API, consulte a federação de identidades de cargas de trabalho.