Chaves API

As chaves API permitem-te usar o Dashboard.PT de forma programática, em vez de apenas através da interface web. Com uma chave podes enviar dados para os teus gráficos a partir dos teus próprios scripts, ler recursos e ligar a plataforma às tuas aplicações e automações. Esta página mostra-te como criar uma chave, como a enviar para autenticar os teus pedidos e as práticas de segurança que mantêm a tua conta protegida.

Visão geral

Uma chave API é um token secreto que identifica a tua conta perante a API. Qualquer pedido que traga uma chave válida é tratado como vindo de ti, por isso uma chave é tão sensível como uma palavra-passe. Cada chave que crias fica associada à tua conta e conta para o limite de chaves API do teu plano.

O que podes fazer com uma chave

  • Enviar dados para os teus gráficos a partir de scripts, servidores ou dispositivos externos.
  • Ler recursos como os teus dashboards, gráficos e monitores.
  • Automatizar tarefas recorrentes e integrar o Dashboard.PT com outras ferramentas.

Criar uma chave

Geres as chaves na secção Chaves API da tua conta.

  1. Abre a secção Chaves API. Encontra-la na barra lateral esquerda da tua conta.
  2. Cria uma nova chave. Dá-lhe um nome claro que diga para que serve, como a integração ou o servidor que a vai usar.
  3. Copia a chave logo de imediato. Guarda-a num sítio seguro assim que for mostrada — por segurança, o valor completo pode não voltar a ser apresentado mais tarde.
  4. Usa-a na tua integração. Adiciona a chave ao script ou serviço que vai chamar a API.

Nota: O número de chaves API que podes ter é definido pelo teu plano (o limite api_keys). Se atingires o limite, revoga uma chave que já não uses antes de criar uma nova.

Autenticar pedidos

Para provar quem és, envia a tua chave em cada pedido como um cabeçalho HTTP e não no URL. Mantê-la fora do endereço significa que não fica registada no histórico do navegador, em proxies ou nos logs de acesso do servidor.

Envia a chave como cabeçalho

  • Adiciona o cabeçalho HTTP Authorization: Bearer A_TUA_CHAVE_API. É o único formato aceite pela API.
  • Substitui A_TUA_CHAVE_API pelo valor que copiaste quando a chave foi criada.
  • Nunca coloques a chave na query string do URL.

Um pedido a partir da linha de comandos tem este aspeto:

curl -H "Authorization: Bearer A_TUA_CHAVE_API" https://dashboard.pt/api/...

Boas práticas de segurança

Como uma chave dá acesso à tua conta, trata-a com o mesmo cuidado que uma palavra-passe.

Mantém as tuas chaves seguras

  • Mantém as chaves secretas. Não as partilhes em emails, mensagens de chat ou capturas de ecrã.
  • Nunca coloques uma chave no código ou em repositórios. Guarda-a numa variável de ambiente ou num gestor de segredos, não em código-fonte que possa ir para o Git.
  • Usa uma chave separada por integração. Se uma for exposta, podes revogar apenas essa chave sem afetar as outras integrações.
  • Revoga e roda. Apaga as chaves que já não usas e roda qualquer chave que suspeites ter sido exposta.

Resumo rápido

Item Detalhes
Onde gerir as chaves A secção Chaves API da tua conta
Como autenticar Envia a chave num cabeçalho HTTP, nunca no URL
Quantas chaves Definido pelo teu plano (o limite api_keys)
Se uma chave for exposta Revoga-a imediatamente e cria uma substituta
Uma chave por Integração, script ou serviço

Saber mais

Esta página cobre como as chaves são criadas e enviadas. Para os formatos de pedido e resposta, os endpoints disponíveis e como os erros são reportados, consulta a documentação relacionada:

  • Referência da API REST — os endpoints disponíveis e o que cada um faz.
  • Pedidos e Respostas da API — como estruturar as chamadas e ler os dados devolvidos.
  • Tratamento de Erros da API — os códigos de erro que podes receber e como reagir a eles.

Gerir as chaves existentes

As chaves não são apenas criadas e esquecidas. Revê-las de tempos a tempos mantém a tua conta organizada e segura.

Boa manutenção

  • Revê a tua lista. Verifica as chaves que tens e confirma que cada uma continua em uso.
  • Revoga as que não usas. Apaga as chaves associadas a integrações que já desativaste para libertar a quota do teu plano.
  • Roda com regularidade. Substituir periodicamente as chaves de longa duração limita os danos se alguma for exposta sem te aperceberes.

Dicas

Dica: Revoga uma chave imediatamente se suspeitares que foi exposta. Criar uma nova chave e atualizar a integração afetada é muito mais barato do que lidar com acessos não autorizados.

Dica: Dá a cada chave o nome da integração que a usa. Nomes claros tornam óbvio qual a chave a revogar ou rodar quando algo muda.

Quer experimentar? O plano gratuito não tem limite de tempo.

Criar conta gratuita