> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myunite.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Chaves de API, permissões, validade e revogação.

Toda chamada à API leva uma chave de API no cabeçalho `Authorization`.

```bash curl theme={null}
curl https://myunite.ai/api/v1/quota \
  -H "Authorization: Bearer $UNITE_API_KEY"
```

```javascript JavaScript theme={null}
const res = await fetch("https://myunite.ai/api/v1/quota", {
  headers: { Authorization: `Bearer ${process.env.UNITE_API_KEY}` },
});
console.log(await res.json());
```

```python Python theme={null}
import os
import requests

res = requests.get(
    "https://myunite.ai/api/v1/quota",
    headers={"Authorization": f"Bearer {os.environ['UNITE_API_KEY']}"},
)
print(res.json())
```

## 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.

> [!WARNING]
>
> 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](https://docs.myunite.ai/webhooks.md). A API precisa estar liberada para o workspace. Se não estiver, a tela avisa e a API responde [`feature_not_enabled`](https://docs.myunite.ai/errors#feature_not_enabled).

## Permissões

Cada chave tem uma ou mais permissões (escopos).

| Escopo | Permite |
| - | - |
| `pretests:read` | Ler o catálogo, a cota, a lista e o detalhe dos pré-testes e baixar o PDF. |
| `pretests:write` | Pedir o endereço de envio de arquivo e criar pré-testes. |
| `webhooks:manage` | Criar, listar e apagar endpoints de [webhook](https://docs.myunite.ai/webhooks.md), enviar um teste e ver os envios. |

Para o fluxo completo do [primeiro pré-teste](https://docs.myunite.ai/quickstart.md), a chave precisa dos dois escopos. Sem o escopo exigido, a resposta é [`insufficient_scope`](https://docs.myunite.ai/errors#insufficient_scope). Dê a cada integração só o que ela usa.

Receber avisos por [webhooks](https://docs.myunite.ai/webhooks.md) 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`](https://docs.myunite.ai/errors#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`](https://docs.myunite.ai/errors#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](https://docs.myunite.ai/webhooks.md) 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`](https://docs.myunite.ai/errors#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`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.