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.

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.

Na prática, esse é o ponto em que a API deixa de trabalhar apenas com governança de consumo e passa a ter autorização mais fina por recurso.

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 emissão de refresh token, ativação ou inativação do cliente e rotação de segredo do cliente.

Como pensar a escolha

Use apenas chave de API quando o cenário pede identificação 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.

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.

Se o cliente usa segredo, trate esse valor como credencial sensível e planeje rotação quando necessário.

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.