Chaves de API
Escolha uma autorização pessoal ou de serviço, guarde o segredo assim que é apresentado e substitua as credenciais sem perder de vista os clientes que as utilizam.
Uma chave de API permite a um cliente atuar com um nível de autorização definido. Uma chave pessoal reflete o vínculo de uma pessoa à organização e as respetivas permissões. Uma chave de serviço da organização pertence à própria organização, permitindo que a automatização não dependa da permanência de um colega. Com RBAC, uma chave de serviço também pode ter uma função e um âmbito de recursos próprios.
O segredo é apresentado no momento da criação e não pode ser recuperado mais tarde a partir dos registos da chave. Guarde-o de imediato num gestor de segredos ou no repositório de credenciais suportado pelo cliente. Não o inclua em ficheiros de código-fonte, configurações guardadas no controlo de versões, capturas de ecrã ou mensagens de suporte.
Utilize uma chave pessoal para trabalhar em nome próprio #
Nas Definições → Chaves de API → Pessoal da organização selecionada, crie uma chave pessoal e atribua-lhe um nome. Qualquer membro pode criar uma para uso próprio. A autorização da chave reflete o vínculo atual de quem a criou à organização e as suas permissões efetivas; ao contrário de uma chave de serviço, não pode ter uma função independente nem um âmbito por motor de localização.
Esta opção é útil para um cliente local que atua em nome de quem o opera. Se o membro sair da organização ou perder a autorização, o acesso da chave também muda. Utilize uma chave de serviço quando a automatização da organização não deva depender de essa pessoa continuar a ter acesso.
Crie uma chave de serviço #
Nas Definiçõ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: esta permite ler e traduzir com todos os motores de localização da organização. O formulário de criação apresenta uma nota em vez dos campos de função e motor.
Este acesso básico não permite que a chave edite ou elimine motores de localização, efetue a revisão de traduções ou administre a organização.
Com RBAC, pode atribuir à chave uma função, um âmbito de motores de localização ou ambos, e alterá-los mais tarde. O cliente tem de poder delegar a função selecionada e traduzir com todos os motores de localização abrangidos pelo âmbito. A permissão de leitura, por si só, não basta para conceder um âmbito de tradução.
As funções permitidas para chaves de serviço são engine:read e engine:translate. A função tem de pertencer à organização e não pode incluir permissões administrativas mais abrangentes. Uma chave de serviço também pode não ter qualquer função e depender de concessões deliberadas de acesso a recursos.
Configure separadamente o âmbito dos motores de localização e o dos recursos de conteúdo. Em seguida, volte a consultar cada campo guardado. Uma atualização de autorização pode falhar enquanto outra é bem-sucedida. As permissões das funções e as concessões explícitas acumulam-se; um âmbito restrito não anula o acesso mais amplo conferido por uma função. Com RBAC, criar a chave, por si só, não lhe concede autorização efetiva para traduzir se não tiver uma função adequada nem concessões de acesso a recursos.
Utilize a interface de gestão de chaves para criar chaves e editar âmbitos. Ao automatizar este ciclo de vida, confirme que o cliente escolhido disponibiliza a operação de gestão necessária, em vez de presumir que todos os clientes o fazem.
Antes de remover o RBAC
Se o RBAC for removido, as chaves de serviço comuns passam a ter acesso de leitura e tradução em toda a organização. As restrições de função e de motor guardadas deixam de limitar esse acesso. Se essas restrições forem necessárias, revogue ou substitua as chaves antes de remover o RBAC. As credenciais para fins específicos, como as chaves SCIM, têm requisitos de acesso próprios.
Substitua ou revogue uma credencial #
A rotação consiste numa substituição manual:
- Crie uma chave de substituição do tipo pretendido e com o nível mínimo de autorização necessário.
- Guarde o respetivo segredo no mecanismo de gestão de segredos do cliente.
- Atualize os clientes dependentes e teste uma pequena operação prevista através da interface que suportam.
- Revogue a chave antiga após a verificação. Se a exposição exigir contenção imediata, revogue-a primeiro e tenha em conta a interrupção.
- Verifique os registos atuais das chaves e as falhas dos clientes para identificar dependências que tenham passado despercebidas.
Um membro da organização com acesso ao registo da chave pode revogar uma chave pessoal ou de serviço comum. Esta permissão de revogação é mais abrangente do que a permissão para criar uma chave de serviço ou editar o respetivo âmbito. A revogação de chaves SCIM exige a intervenção do Proprietário da organização. Ao falar da remoção, refira o identificador da chave, não o respetivo segredo.
A revogação não apaga cópias guardadas noutros locais nem revoga sessões do navegador. Este ciclo de vida não pressupõe qualquer calendário automático de rotação ou expiração.
Configure o cliente que vai efetuar as chamadas #
Os pedidos REST utilizam o cabeçalho X-API-Key da API selecionada. Um código 401 aponta para um problema de autenticação; um código 403 aponta para uma autorização recusada. No primeiro caso, confirme a credencial; no segundo, confirme as permissões e o âmbito de recursos da entidade autenticada. Não inclua credenciais em URLs improvisados.
Consulte Autenticação da API, Autenticação da CLI ou o Contrato de ligação MCP para conhecer o comportamento do cliente na comunicação e no armazenamento. O motor de localização selecionado tem de se manter dentro do âmbito de autorização desse cliente.