Autenticação

A AstroAPI suporta múltiplos métodos de autenticação consoante o caso de uso.

Autenticação por Chave de API

As chaves de API são o método recomendado para comunicação servidor-a-servidor.

Obter uma Chave de API

1. Inicia sessão no Dashboard da AstroAPI
2. Navega até Settings > API Keys
3. Clica em Create API Key
4. Configura as permissões e os limites de utilização
5. Copia a chave gerada (não será mostrada novamente)

Utilizar Chaves de API

Inclui a tua chave de API no cabeçalho X-Api-Key:

curl -X GET "https://api.astroapi.cloud/api/calc/natal" \
  -H "X-Api-Key: ak_live_xxxxxxxxxxxx"

Permissões das Chaves de API

As chaves de API podem ser limitadas a permissões específicas:

Permissão	Descrição
calc:read	Acesso aos endpoints de cálculo
content:read	Acesso aos endpoints de conteúdo/interpretação
chart:read	Acesso aos endpoints de renderização de mapas
modules:read	Acesso aos módulos adquiridos

Funções

A AstroAPI utiliza controlo de acesso baseado em funções dentro das organizações:

Função	Descrição
owner	Acesso total a todas as funcionalidades da organização
manager	Pode gerir utilizadores, faturação e conteúdo
member	Acesso básico a cálculos e leitura de conteúdo

Permissões por Função

Permissão	owner	manager	member	Descrição
org:create	✅			Criar organização
org:read	✅	✅	✅	Ler organização
org:update	✅	✅		Atualizar organização
org:users:read	✅	✅		Ler utilizadores
org:users:create	✅	✅		Convidar utilizadores
org:users:update	✅	✅		Atualizar utilizadores
org:users:delete	✅	✅		Remover utilizadores
billing:read	✅	✅		Ver faturação
billing:manage	✅	✅		Gerir faturação
content:read	✅	✅	✅	Ler conteúdo
content:create	✅	✅		Criar conteúdo
content:update	✅	✅		Atualizar conteúdo
content:delete	✅	✅		Eliminar conteúdo
content:custom-copy	✅	✅	✅	Criar cópias personalizadas
content:restore	✅	✅		Restaurar conteúdo
calc:use	✅	✅	✅	Usar endpoints de cálculo
chart:use	✅	✅	✅	Usar endpoints de mapas
modules:read	✅	✅	✅	Ler informação de módulos
admin:access	✅			Acesso de administrador

Contexto de Organização

Para aplicações multi-tenant, as chaves de API estão associadas a organizações. O contexto da organização é aplicado automaticamente com base na chave de API utilizada.

Restrições de Domínio

As chaves de API podem ser configuradas com restrições de domínio para limitar quais os sites que as podem utilizar:

• example.com — Correspondência exacta de domínio
• *.example.com — Todos os subdomínios
• * — Permitir todos os domínios (não recomendado)

Configura as restrições de domínio no dashboard ao criar ou editar uma chave de API.

Limitação Importante

As restrições de domínio apenas protegem contra utilização abusiva a partir do browser. Baseiam-se nos cabeçalhos Origin e Referer, que os browsers aplicam, mas que podem ser facilmente falsificados fora do browser (por exemplo, com curl, scripts ou código do lado do servidor).

Utilização no Cliente vs. no Servidor

Servidor-a-Servidor (Recomendado)

Para aplicações em produção, usa sempre chaves de API no teu servidor de backend:

┌─────────────┐      ┌─────────────────┐      ┌─────────────┐
│   Browser   │ ───► │  O teu Backend  │ ───► │  AstroAPI   │
│ (sem chaves)│      │  (chave aqui)   │      │             │
└─────────────┘      └─────────────────┘      └─────────────┘

Esta abordagem:

• Mantém a tua chave de API segura e oculta
• Permite-te adicionar a tua própria camada de autenticação
• Impede a extracção da chave de API pelos utilizadores finais
• Permite assinatura de pedidos e medidas de segurança adicionais

Utilização no Cliente / Browser

Se tiveres de utilizar chaves de API directamente no browser (por exemplo, widgets embutidos em sites estáticos), tem em atenção as limitações:

• As chaves de API são visíveis no código-fonte JavaScript e nos pedidos de rede
• Qualquer pessoa pode extrair a chave do teu site
• As restrições de domínio apenas impedem outros sites de utilizarem a tua chave via JavaScript — não impedem alguém de copiar a chave e usá-la noutro lugar

Para utilização no cliente, recomendamos:

• Activar restrições de domínio
• Definir limites de utilização estritos
• Usar tempos de expiração curtos
• Monitorizar a utilização para detectar anomalias

Responsabilidade do Cliente

Importante

És responsável pela segurança e utilização das tuas chaves de API.

Todos os pedidos de API feitos com a tua chave de API contam para a tua quota e são cobrados à tua conta, independentemente de terem sido feitos por ti ou por alguém que obteve a tua chave.

Se expuseres uma chave de API em código do lado do cliente e esta for utilizada de forma abusiva, és responsável pela utilização e pelos custos resultantes. A AstroAPI não consegue distinguir entre pedidos legítimos e pedidos não autorizados feitos com uma chave de API válida.

Para minimizar o risco:

1. Usa comunicação servidor-a-servidor sempre que possível
2. Nunca faças commit de chaves de API para controlo de versões
3. Roda as chaves imediatamente se suspeitares que foram comprometidas
4. Configura alertas de utilização para detectar picos inesperados

Boas Práticas de Segurança

• Usa comunicação servidor-a-servidor para aplicações em produção
• Nunca exponhas chaves de API em código do lado do cliente, a menos que seja absolutamente necessário
• Roda as chaves de API periodicamente
• Usa as permissões mínimas necessárias
• Activa restrições de domínio para chaves do lado do cliente
• Define limites de utilização adequados
• Monitoriza a utilização das chaves de API no dashboard