Autenticação e autorização em APIs: Basic, API Key e Bearer/JWT

Conceitos essenciais: autenticação vs autorização

Em testes de API, é comum ver os termos “autenticação” e “autorização” sendo usados como se fossem a mesma coisa, mas eles resolvem problemas diferentes. Autenticação responde à pergunta “quem é você?” e normalmente acontece quando o cliente apresenta uma credencial (usuário/senha, token, chave). Autorização responde à pergunta “o que você pode fazer?” e normalmente depende de regras de acesso (escopos, perfis, roles, permissões por recurso) aplicadas após a identidade do cliente ser reconhecida.

Na prática, uma mesma requisição pode falhar por motivos diferentes: uma falha de autenticação costuma resultar em 401 (credencial ausente, inválida ou expirada), enquanto uma falha de autorização costuma resultar em 403 (credencial válida, mas sem permissão para executar a ação). Em rotinas de QA, separar esses dois tipos de falha ajuda a diagnosticar rapidamente se o problema está na credencial, no fluxo de obtenção do token, no escopo/role do usuário, ou na regra de acesso do endpoint.

Onde as credenciais viajam: headers, query string e body

APIs podem receber credenciais em diferentes lugares, mas o padrão mais comum e recomendado é o header HTTP, especialmente o header Authorization. Em alguns casos, a API Key pode ser enviada em um header específico (por exemplo, x-api-key) ou como parâmetro de query (por exemplo, ?api_key=...). Para testes, é importante validar não só o “caminho feliz”, mas também variações: credencial ausente, credencial em local errado, credencial com formato incorreto, credencial expirada e credencial com privilégios insuficientes.

No Postman, isso se traduz em configurar corretamente a aba Authorization (quando disponível) ou inserir headers manualmente, e também em automatizar a troca de credenciais por ambiente (dev, homolog, prod) usando variáveis. Assim, você evita editar requisições uma a uma e diminui o risco de vazar segredos em coleções compartilhadas.

Basic Authentication (usuário e senha)

O que é e quando aparece

Basic Auth é um esquema simples em que o cliente envia usuário e senha em todas as requisições (ou em todas as requisições que exigem autenticação). Tecnicamente, o header Authorization recebe o valor “Basic ” seguido de uma string Base64 do formato usuario:senha. Base64 não é criptografia; é apenas codificação. Por isso, Basic Auth deve ser usado somente com HTTPS, caso contrário as credenciais podem ser interceptadas.

Continue em nosso aplicativo

Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.

ou continue lendo abaixo...

Baixar o aplicativo

Em APIs internas, gateways, ferramentas administrativas ou endpoints legados, Basic Auth ainda é comum. Em cenários modernos, ele pode aparecer como etapa inicial para obter um token (por exemplo, trocar usuário/senha por um token Bearer), reduzindo a exposição da senha no restante do tráfego.

Como configurar no Postman (passo a passo)

• Abra a requisição no Postman e vá até a aba Authorization.
• Em Type, selecione Basic Auth.
• Preencha Username e Password.
• Verifique se o Postman está adicionando o header Authorization automaticamente (você pode conferir na aba Headers).
• Envie a requisição e observe o status code e o corpo da resposta.

Quando você usa a aba Authorization, o Postman monta o header automaticamente. Se você preferir montar manualmente, pode criar o header Authorization com o valor “Basic ...”, mas isso aumenta o risco de erro e de exposição acidental do valor codificado.

Boas práticas de teste para Basic Auth

• Teste credenciais válidas e inválidas: usuário correto com senha errada, usuário inexistente, senha vazia.
• Teste ausência do header Authorization: a API deve responder 401 e, idealmente, informar o esquema esperado no header WWW-Authenticate.
• Teste com caracteres especiais no usuário/senha: valide se o servidor interpreta corretamente.
• Teste repetição de chamadas: como a senha vai em todas as requisições, verifique se há rate limit ou bloqueio após tentativas falhas.

Exemplo de header (referência)

Authorization: Basic dXN1YXJpbzpzZW5oYQ==

O valor após “Basic” é Base64 de “usuario:senha”. Em testes, evite registrar esse valor em logs ou documentação pública.

API Key (chave de acesso)

O que é e como costuma ser usada

API Key é uma credencial estática (uma “chave”) que identifica o consumidor da API ou o aplicativo cliente. Ela pode representar um projeto, uma integração, um parceiro ou um tenant. Diferente de usuário/senha, a API Key geralmente não representa uma pessoa, e sim um cliente técnico. Em muitos sistemas, a API Key é combinada com outras camadas, como IP allowlist, quotas, rate limiting, assinatura HMAC, ou ainda com um token de usuário para autorização fina.

Um ponto importante: API Key sozinha frequentemente oferece autenticação do cliente, mas não necessariamente autorização detalhada por usuário. Por isso, em testes, você deve confirmar se a chave apenas “abre a porta” e se as permissões são controladas por outros mecanismos (por exemplo, roles no token, escopos, ou regras por endpoint).

Locais comuns para enviar a API Key

• Header dedicado: x-api-key: SUA_CHAVE
• Header Authorization com esquema próprio: Authorization: ApiKey SUA_CHAVE (varia por API)
• Query string: ?api_key=SUA_CHAVE (menos recomendado por exposição em logs e caches)

Quando a API aceita query string, é comum que proxies, servidores e ferramentas registrem a URL completa em logs, o que pode vazar a chave. Em QA, vale validar se a API rejeita chaves em locais não suportados e se a documentação está alinhada com o comportamento real.

Como configurar no Postman (passo a passo)

Como “API Key” não é um padrão único, você normalmente configura via headers ou pela opção Authorization quando a API segue um formato suportado. Um fluxo prático e seguro é usar variáveis de ambiente.

• Crie/abra um Environment e adicione uma variável, por exemplo api_key, com o valor da chave (marque como secret quando disponível, ou mantenha fora de exports públicos).
• Na requisição, vá em Headers e adicione a chave conforme o contrato da API. Exemplo: Key = x-api-key, Value = {{api_key}}.
• Envie a requisição e valide o retorno.

Testes essenciais para API Key

• Chave ausente: deve retornar 401 ou 403 (depende do design), com mensagem clara.
• Chave inválida: deve retornar 401/403 sem revelar detalhes sensíveis (por exemplo, não informar se a chave existe).
• Chave revogada: simular uma chave desativada e validar o comportamento.
• Escopo por chave: se a API Key estiver associada a um “plano” ou “produto”, valide endpoints permitidos e bloqueados.
• Rate limiting: valide se a API responde com 429 quando excede limites e se os headers de rate limit (quando existirem) estão presentes.

Exemplo de header (referência)

x-api-key: {{api_key}}

Bearer Token e JWT

O que é Bearer Token

Bearer Token é um esquema em que o cliente envia um token no header Authorization no formato “Bearer <token>”. O termo “bearer” indica que quem “porta” o token consegue acessar os recursos associados a ele; portanto, o token deve ser protegido como um segredo. Esse modelo é muito comum em OAuth 2.0 e em autenticação baseada em sessão stateless.

O token pode ser opaco (uma string sem significado para o cliente) ou pode ser um JWT (JSON Web Token), que carrega claims em formato JSON e é assinado (e às vezes criptografado). Em ambos os casos, o servidor valida o token e decide se a requisição está autenticada e autorizada.

O que é JWT e como interpretar sem “quebrar” segurança

JWT é composto por três partes separadas por ponto: header.payload.signature. O payload costuma ser Base64URL de um JSON com claims como sub (identificador do usuário), exp (expiração), iss (emissor), aud (audiência), e possivelmente roles/permissions/scopes. A assinatura garante integridade: o cliente não pode alterar o payload sem invalidar a assinatura.

Em QA, interpretar o JWT ajuda a entender por que uma requisição foi negada: token expirado (exp no passado), token emitido para outra audiência (aud diferente), emissor incorreto (iss), ou ausência de escopos/roles necessários. Porém, não é uma boa prática “confiar” no payload do JWT do lado do cliente para decisões de segurança; isso é responsabilidade do servidor. Para testes, você pode decodificar o JWT apenas para inspeção e diagnóstico, sem alterar o token.

Como obter e usar um Bearer Token no Postman (passo a passo)

O fluxo exato depende da API, mas um padrão muito comum é: chamar um endpoint de login/token, extrair o access_token da resposta e reutilizar nas demais requisições. O Postman permite automatizar isso com scripts de teste e variáveis.

Passo 1: criar uma requisição de obtenção de token

Crie uma requisição chamada, por exemplo, “Auth - Token”. Ela pode ser um POST para /auth/token ou /login, conforme a API. O body pode ser JSON com usuário/senha, ou form-urlencoded, dependendo do contrato. O objetivo é receber um campo como access_token.

Passo 2: salvar o token em variável ao receber a resposta

Na requisição “Auth - Token”, vá até a aba Tests e adicione um script para capturar o token e salvar no ambiente. Exemplo genérico (ajuste o caminho conforme a resposta real):

const json = pm.response.json();pm.environment.set('access_token', json.access_token);

Se a resposta vier aninhada (por exemplo, data.token), ajuste para json.data.token. Se a API retornar também expires_in, você pode armazenar para controle de expiração em rotinas mais avançadas.

Passo 3: usar o token nas requisições protegidas

Em cada requisição que exige autenticação, você pode configurar de duas formas:

• Pela aba Authorization: Type = Bearer Token e Token = {{access_token}}.
• Ou manualmente em Headers: Authorization = Bearer {{access_token}}.

A opção pela aba Authorization tende a ser mais clara e reduz conflitos com headers duplicados.

Passo 4: validar falhas comuns (expiração, ausência e token inválido)

• Sem token: remova o header Authorization e valide 401.
• Token inválido: altere um caractere do token e valide 401 (ou 403, dependendo da API).
• Token expirado: use um token antigo e valide a mensagem/erro retornado.
• Token de outro usuário/role: valide 403 ao acessar recursos não permitidos.

Exemplo de header (referência)

Authorization: Bearer {{access_token}}

Automatizando a autenticação em coleções: pré-requisições e encadeamento

Estratégia 1: rodar a requisição de token antes das demais

Uma abordagem simples é colocar a requisição “Auth - Token” no início da coleção e garantir que ela execute antes das requisições protegidas. Em execução manual, você envia primeiro o token e depois segue. Em execução automatizada (Collection Runner), a ordem da coleção garante que a variável access_token esteja preenchida.

Estratégia 2: usar Pre-request Script para renovar token quando necessário

Quando o token expira rapidamente, você pode implementar uma lógica de “se não existe token, ou se expirou, obter novamente”. Isso exige que você armazene também um timestamp de expiração. Um exemplo de ideia (genérica) é salvar a hora atual + expires_in ao obter o token, e antes de cada requisição verificar se já passou. A implementação exata depende do formato do retorno do endpoint de token.

Exemplo de armazenamento na requisição de token (Tests):

const json = pm.response.json();pm.environment.set('access_token', json.access_token);const expiresIn = json.expires_in || 0;const expiresAt = Date.now() + (expiresIn * 1000);pm.environment.set('access_token_expires_at', String(expiresAt));

Exemplo de checagem simples (Pre-request Script) em requisições protegidas:

const token = pm.environment.get('access_token');const expiresAt = Number(pm.environment.get('access_token_expires_at') || 0);if (!token || (expiresAt && Date.now() >= expiresAt)) {  postman.setNextRequest('Auth - Token');}

Esse padrão faz o fluxo “voltar” para a requisição de token quando necessário. É importante que a requisição “Auth - Token” ao terminar siga para a requisição original; você pode controlar isso organizando a ordem da coleção ou usando setNextRequest com cuidado. Em QA, o objetivo é reduzir falhas intermitentes por expiração durante uma bateria de testes.

Validações de segurança e comportamento que QA deve cobrir

Mapeando respostas 401 vs 403

Crie casos de teste que diferenciem claramente: (1) sem credencial, (2) credencial inválida, (3) credencial válida sem permissão. Isso ajuda a detectar configurações incorretas no gateway, como retornar 403 para tudo (o que dificulta diagnóstico) ou retornar 401 mesmo quando o usuário está autenticado mas não autorizado.

Escopos, roles e permissões por endpoint

Em Bearer/JWT, a autorização frequentemente depende de claims como scope, roles ou permissions. Mesmo que você não controle a emissão do token, você pode testar com usuários diferentes (por exemplo, um usuário “admin” e um usuário “leitura”) e validar que endpoints de escrita são bloqueados para quem não tem permissão. O foco aqui é garantir que a API não permita escalonamento de privilégio, como um usuário comum acessando rotas administrativas.

Testando vazamento de informação em mensagens de erro

Mensagens de erro não devem revelar detalhes sensíveis, como “API Key válida, mas sem permissão X” ou “usuário existe, senha incorreta”. Em testes, observe se a API retorna mensagens genéricas e se mantém consistência. Isso não impede o QA de diagnosticar, mas reduz vetores de enumeração para atacantes.

Reuso e revogação

Para API Key, valide se existe mecanismo de revogação e se a chave revogada para de funcionar imediatamente. Para Bearer/JWT, valide o comportamento após logout (quando aplicável) e em cenários de rotação de chaves de assinatura (quando o emissor troca o segredo/certificado). Em ambientes corporativos, falhas de revogação podem causar incidentes de segurança.

Organizando credenciais no Postman com segurança

Variáveis por ambiente e segregação de segredos

Armazene credenciais em variáveis de ambiente, não diretamente em requisições. Use nomes claros como api_key, username, password, access_token. Evite exportar ambientes com segredos para repositórios públicos. Se você precisa compartilhar a coleção, compartilhe sem os valores sensíveis e instrua o time a preencher localmente.

Evitar duplicidade de headers e conflitos

Um erro comum é configurar Authorization na aba Authorization e também adicionar manualmente um header Authorization em Headers. Isso pode gerar comportamento inesperado, como o Postman enviar dois headers ou sobrescrever valores. Padronize: ou use a aba Authorization, ou use headers manuais, e mantenha consistência na coleção.

Checklist rápido por método

• Basic: confirmar HTTPS, validar 401 sem header, evitar log de credenciais.
• API Key: preferir header, validar rate limit, validar revogação e escopo por chave.
• Bearer/JWT: automatizar captura do token, validar expiração, validar 401 vs 403, validar permissões por usuário/role.