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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tunnelhub.io/api-management/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.