Autenticação - EnemHub API

Toda rota sob /v1/vestibulares exige uma API Key. Mande a chave no header X-API-Key:

curl https://api.enemhub.com.br/v1/vestibulares/exams \
  -H "X-API-Key: ehub_vest_SUA_CHAVE"

Também aceitamos Authorization: Bearer, para clientes HTTP que já têm o campo pronto:

curl https://api.enemhub.com.br/v1/vestibulares/exams \
  -H "Authorization: Bearer ehub_vest_SUA_CHAVE"

As duas formas são equivalentes. X-API-Key tem prioridade se você mandar as duas.

O formato da chave

ehub_vest_aZ3fK9pQ...
                └── 43 caracteres aleatórios (base64url)
      └────────────── produto: `vest` neste caso

Só o hash SHA-256 é armazenado. A chave em claro existe uma única vez, na resposta da criação — depois disso, nem nós conseguimos lê-la.

Escopo: a chave pertence a um produto

Uma chave ehub_vest_... abre as rotas /v1/vestibulares/*. Ela não abre /v1/enem/*, e uma chave ehub_enem_... não abre estas — mesmo que a organização assine os dois produtos. O erro é 403:

{
  "error": "Forbidden",
  "message": "Esta API key (produto: enem) não tem acesso a este endpoint."
}

Assinando este produto, você não precisa da chave do ENEM: o catálogo de vestibulares já inclui as questões do ENEM, acessíveis por /v1/vestibulares/questions com o examId do ENEM.

Onde guardar

A chave é uma credencial de servidor. Ela dá acesso à cota que você paga e não deve ir para o front-end: qualquer pessoa lê o JavaScript da sua página. Chame a EnemHub do seu backend e sirva o resultado para o cliente.

Em variável de ambiente, não no código:

.env

ENEMHUB_API_KEY=ehub_vest_...

Rotação e revogação

Em API Keys você cria, lista e revoga chaves. Para rotacionar sem downtime: crie a nova, atualize a aplicação, confirme que o tráfego migrou e só então revogue a antiga. A revogação é imediata — a chave passa a devolver 401 na requisição seguinte. O teto de chaves ativas vem do plano: 10 no Pro, 50 no Business, ilimitadas no Enterprise.

Erros de autenticação

Status	Corpo	O que checar
`401`	`{ "error": "Unauthorized", "message": "API key inválida, revogada ou expirada." }`	O header chegou? A chave foi revogada ou expirou?
`403`	`{ "error": "Forbidden", "message": "Esta API key (produto: …) não tem acesso a este endpoint." }`	Chave de outro produto — veja o escopo acima.
`403`	`{ "error": "Forbidden", "message": "Nenhuma assinatura ativa para este produto." }`	A assinatura venceu ou foi cancelada. Confira o Faturamento.

Tentativas de autenticação falhas são contadas por IP. Um volume alto de 401 seguidos passa a receber 429 por alguns minutos — é proteção contra força bruta, e some sozinho. Se apareceu na sua aplicação, quase sempre significa que ela está repetindo uma chave errada em loop.

Limites

Toda resposta de /v1/* traz dois headers:

Header	Significado
`X-RateLimit-Limit`	Requisições por minuto permitidas pelo seu plano.
`X-RateLimit-Remaining`	Quantas ainda cabem no minuto corrente.

Ao estourar, a resposta é 429 com Retry-After: 60. São três limites independentes:

Por minuto — definido pelo plano.
Por dia — 10.000 requisições, igual para todos os planos.
Por mês — a cota do plano. Ao estourar, a mensagem pede upgrade.

Uma requisição recusada com 429 não consome cota mensal. Estourar o limite por minuto não queima o seu volume contratado.

Retry com backoff

async function comRetry(url, init, tentativas = 3) {
  for (let i = 0; i < tentativas; i++) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;

    const espera = Number(res.headers.get("Retry-After") ?? 60);
    await new Promise((r) => setTimeout(r, espera * 1000));
  }
  throw new Error("Rate limit persistente após 3 tentativas");
}

​O formato da chave

​Escopo: a chave pertence a um produto

​Onde guardar

​Rotação e revogação

​Erros de autenticação

​Limites

O formato da chave

Escopo: a chave pertence a um produto

Onde guardar

Rotação e revogação

Erros de autenticação

Limites