Chaves de API
Escolha entre permissões pessoais ou de serviço, guarde o segredo assim que ele for exibido e substitua credenciais sem perder de vista os clientes que as utilizam.
Uma chave de API permite que um cliente atue com permissões definidas. Uma chave pessoal acompanha o vínculo e as permissões de quem a criou. Já uma chave de serviço pertence à organização, para que a automação não dependa da permanência de um colega na equipe. Com RBAC, uma chave de serviço também pode ter sua própria função e seu próprio escopo de recursos.
O segredo é exibido na criação e não pode ser recuperado depois nos registros da chave. Guarde-o imediatamente em um gerenciador de segredos ou no repositório de credenciais compatível com o cliente. Não o inclua em arquivos de código-fonte, configurações versionadas, capturas de tela ou mensagens de suporte.
Usar uma chave pessoal para atuar em nome de uma pessoa #
Em Configurações → Chaves de API → Pessoal da organização selecionada, crie uma chave pessoal e dê um nome a ela. Qualquer membro pode criar uma para uso próprio. O acesso da chave acompanha o vínculo atual e as permissões efetivas de quem a criou. Ao contrário de uma chave de serviço, ela não pode receber uma função separada nem ter o escopo limitado a engines de localização específicos.
Essa opção é útil para um cliente local que atua em nome de seu operador. Se o membro sair da organização ou perder permissões, o acesso da chave também mudará. Use uma chave de serviço quando a automação da organização não puder depender da continuidade do acesso dessa pessoa.
Criar uma chave de serviço #
Em Configurações → Chaves de API → Organização da organização selecionada, selecione Nova chave da organização. As chaves de serviço estão disponíveis em todos os planos. Para criar uma, é necessário org:manage_api_keys.
Sem RBAC, não é possível restringir o acesso de uma chave de serviço: ela permite ler e traduzir com todos os engines de localização da organização. O formulário de criação exibe uma observação no lugar dos campos de função e engine.
Esse acesso básico não permite que a chave edite ou exclua engines de localização, revise traduções ou administre a organização.
Com RBAC, você pode atribuir à chave uma função, um escopo de engines de localização ou ambos, e alterá-los depois. O cliente precisa ter permissão para delegar a função selecionada e traduzir com todos os engines de localização do escopo. A permissão de leitura, por si só, não basta para conceder um escopo de tradução.
As funções permitidas para chaves de serviço são engine:read e engine:translate. A função deve pertencer à organização e não pode incluir permissões administrativas mais amplas. Uma chave de serviço também pode ficar sem função e depender de concessões explícitas de acesso a recursos.
Configure separadamente o escopo de engines de localização e o de recursos de conteúdo. Depois, consulte novamente cada campo salvo. Uma atualização de permissões pode falhar enquanto outra é concluída com sucesso. As permissões da função e as concessões explícitas se somam; um escopo restrito não anula um acesso mais amplo concedido pela função. Com RBAC, apenas criar a chave não concede permissões úteis de tradução se ela não tiver uma função adequada nem concessões de acesso a recursos.
Use a interface de gerenciamento de chaves para criar chaves e editar escopos. Ao automatizar esse ciclo de vida, verifique se o cliente escolhido oferece a operação de gerenciamento necessária, em vez de presumir que todos os clientes a disponibilizam.
Antes de remover o RBAC
Se o RBAC for removido, as chaves de serviço comuns voltam a ter acesso de leitura e tradução em toda a organização. As restrições de função e engine armazenadas deixam de limitar esse acesso. Se essas restrições forem necessárias, revogue ou substitua as chaves antes de remover o RBAC. Credenciais para finalidades específicas, como chaves SCIM, têm requisitos de acesso próprios.
Substituir ou revogar uma credencial #
A rotação consiste em uma substituição manual:
- Crie uma chave substituta do tipo desejado, com apenas as permissões mínimas necessárias.
- Guarde o segredo da nova chave no mecanismo de gerenciamento de segredos do cliente.
- Atualize os clientes que dependem da chave e teste uma operação simples de uso previsto pela interface compatível com cada um.
- Revogue a chave antiga após a verificação. Se a exposição exigir contenção imediata, revogue primeiro e leve em conta a interrupção.
- Confira os registros atuais das chaves e as falhas dos clientes para identificar dependências que passaram despercebidas.
Um membro da organização com acesso ao registro da chave pode revogar uma chave pessoal ou de serviço comum. Essa permissão de revogação é mais ampla do que a permissão para criar uma chave de serviço ou editar seu escopo. Somente o Proprietário da organização pode revogar chaves SCIM. Ao tratar da remoção, use o identificador da chave, nunca o segredo.
A revogação não apaga cópias mantidas em outros locais nem revoga sessões do navegador. Esse ciclo de vida não implica uma programação automática de rotação ou expiração.
Configurar o cliente que fará as chamadas #
As requisições REST usam o cabeçalho X-API-Key da API selecionada. Um erro 401 indica um problema de autenticação; um erro 403 indica que a autorização foi negada. No primeiro caso, confira a credencial; no segundo, as permissões e o escopo de recursos da identidade que faz a chamada. Não inclua credenciais em URLs improvisadas.
Consulte Autenticação da API, Autenticação da CLI ou o Contrato de conexão MCP para saber como o cliente transmite e armazena credenciais. O engine de localização selecionado deve permanecer dentro do escopo de permissões desse cliente.