Skip to main content

Autenticação

Todos os endpoints da API (exceto /v1/status) exigem uma API Key válida. A key é enviada em cada requisição através do header HTTP Authorization, no formato Bearer Token. A validação é feita pelo middleware EnsureValidApiKey, que verifica se a key existe na base de dados e está ativa. Não há cookies, sessões ou JWT — cada requisição é autenticada de forma independente.

Como enviar a API Key

Adicione o header Authorization com o prefixo Bearer seguido da sua key:
Nunca exponha sua API Key em repositórios públicos, código client-side ou URLs. Trate-a como uma senha.

Exemplos de código

Substitua SUA_API_KEY pela key fornecida após o cadastro.

Erros de autenticação

Quando a autenticação falha, a API retorna HTTP 401 com um JSON explicativo.

API Key não fornecida

O header Authorization está ausente ou vazio.

API Key inválida ou inativa

A key foi fornecida, mas não existe na base de dados ou foi desativada.

Planos e acesso a endpoints

Cada API Key pertence a um plano que determina quais endpoints e campeonatos estão disponíveis.

Plano Free

O plano free tem acesso limitado a campeonatos brasileiros e aos endpoints de tabela, artilharia e rodadas.
Acessar um endpoint ou campeonato fora do seu plano retorna HTTP 403:

Plano Pro

Acesso completo a todos os endpoints e campeonatos, incluindo Copa do Mundo, partidas ao vivo, eventos, estatísticas, times e jogadores.

Plano Enterprise

Mesmo acesso do Pro, com limites de requisições personalizados.

Rate Limiting

Cada API Key tem um limite de requisições por período, determinado pelo plano associado a ela. Os dois limites (dia e mês) valem em conjunto: ao atingir qualquer um deles, novas requisições retornam 429 Too Many Requests até a renovação da janela.

Headers de rate limit

Toda resposta bem-sucedida inclui headers informando o consumo atual (valores conforme o plano da key):

Obtendo uma API Key

A API é oferecida apenas em produção. Cada cliente recebe uma key própria — não há ambiente de testes público nem keys de sandbox. As keys são gerenciadas em https://dadosfutebol.com.br/api-keys. O administrador pode:
  • Criar keys associadas a um cliente ou aplicação
  • Definir o plano (free, pro, enterprise)
  • Ativar ou desativar uma key a qualquer momento
  • Excluir keys comprometidas
A key pode ser consultada novamente e também revogada/excluída a qualquer momento. Guarde-a em local seguro e não a compartilhe.