# Autenticação

O TunnelHub suporta diferentes estratégias de autenticação para APIs, incluindo chaves de API e fluxos baseados em OAuth com Cognito.

## Visão geral

As duas camadas mais comuns são:

* **Chave de API + plano de uso** para identificação e controle de consumo;
* **OAuth com escopos** para autenticação e autorização mais robustas.

Essas camadas podem coexistir, mas cumprem papéis diferentes. A chave de API ajuda a identificar e governar consumo; OAuth ajuda a autenticar e autorizar acesso a recursos protegidos.

## Quando usar cada uma

Use apenas chave de API quando o cenário pede principalmente governança de consumo e o risco é menor.

Use OAuth quando:

* a API expõe dados sensíveis;
* existe necessidade de escopos finos;
* há múltiplos clientes com acessos diferentes;
* governança e auditoria são importantes.

Em cenários corporativos, o mais comum é combinar controle de consumo com autenticação forte.

## Servidores de recursos

Servidores de recursos agrupam os escopos OAuth que protegem seus endpoints.

Cada servidor de recursos normalmente define:

* nome amigável;
* identificador único;
* lista de escopos com descrição.

Esses escopos podem ser associados a endpoints protegidos.

## Clientes

Clientes representam aplicações consumidoras autenticadas. Eles são usados para cenários machine-to-machine e outros fluxos controlados pela plataforma.

Ao criar um cliente, você normalmente define:

* identificação do cliente;
* expiração de tokens;
* escopos autorizados.

Dependendo do caso, o fluxo também envolve rotação de segredo do cliente, ativação ou inativação e outros controles operacionais.

## Fluxo prático mínimo

Um fluxo típico para uma API protegida costuma ser:

1. definir a API e seus endpoints;
2. decidir quais rotas exigem OAuth;
3. criar ou revisar o servidor de recursos;
4. criar o cliente consumidor;
5. autorizar os escopos corretos;
6. validar a obtenção de token e a chamada autenticada.

## Geração de token

Dependendo do fluxo configurado, a aplicação consumidora troca suas credenciais por um access token e usa esse token para chamar endpoints protegidos.

Na prática, a documentação da API e a configuração do cliente devem deixar claro:

* endpoint de token;
* grant esperado;
* escopos permitidos;
* formato de envio das credenciais.

## Boas práticas

* modele escopos com granularidade suficiente para refletir o negócio;
* evite compartilhar o mesmo cliente entre consumidores distintos;
* documente claramente quais rotas exigem escopos e quais usam apenas governança por chave;
* revise expiração de tokens conforme criticidade e perfil de integração;
* rotacione segredos de clientes sempre que houver suspeita de exposição.