Pular para o conteúdo principal
Toda chamada à API leva uma chave de API no cabeçalho Authorization.

Formato da chave

A chave começa com unite_live_ seguido de 40 letras e números. Nos exemplos desta documentação usamos o valor unite_live_SUA_CHAVE_AQUI, que não funciona. A Unite guarda apenas uma versão irreversível da chave. Por isso o valor completo aparece uma única vez, na criação. Se perder, crie outra e revogue a antiga.
A chave é um segredo de servidor. Não use em navegador, em app de celular nem em repositório. Quem tem a chave faz tudo o que as permissões dela deixam.

Quem cria

Só administradores do workspace criam e revogam chaves, em Chaves de API, no painel do workspace. No mesmo painel, os administradores também gerenciam os endpoints de webhooks. A API precisa estar liberada para o workspace. Se não estiver, a tela avisa e a API responde feature_not_enabled.

Permissões

Cada chave tem uma ou mais permissões (escopos). Para o fluxo completo do primeiro pré-teste, a chave precisa dos dois escopos. Sem o escopo exigido, a resposta é insufficient_scope. Dê a cada integração só o que ela usa. Receber avisos por webhooks exige o escopo webhooks:manage apenas para cadastrar e gerenciar os endpoints. Os eventos em si chegam ao seu servidor sem usar a chave.

Validade

Ao criar, escolha 30, 90 ou 365 dias, ou sem validade. Depois de vencida, a chave responde api_key_expired. Prefira chaves com validade e troque-as antes de vencer.

Revogação

Qualquer administrador revoga uma chave na mesma tela. A revogação vale na hora e não tem volta: a chave passa a responder api_key_revoked. Revogue sempre que suspeitar de vazamento.

A chave age em nome de quem a criou

A chave representa o membro que a criou. Os pré-testes criados por ela ficam no nome dessa pessoa. Se essa pessoa sair do workspace ou perder o acesso a ele, a chave deixa de funcionar. Os endpoints de webhooks criados por essa pessoa também são desativados (disabledReason: "creator_removed"); revogar uma chave, ao contrário, não afeta endpoints. A cada chamada, a Unite confere de novo se essa pessoa ainda é membro ativo do workspace. Se ela sair do workspace ou perder o acesso, a chave para de funcionar e responde key_owner_not_member, mesmo sem ter sido revogada. Para uma integração duradoura, crie a chave com uma conta que deve permanecer no workspace.

Isolamento

A chave só enxerga o workspace em que foi criada. Ids de outro workspace respondem como se não existissem (404).