Authorization.
Formato da chave
A chave começa comunite_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.
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 respondefeature_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 respondeapi_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 responderapi_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).