Autenticação

Quase todos os pedidos à AstroWay API são autenticados com o cabeçalho X-Api-Key. Exceções: os 14 endpoints /v1/reference/* (signs, planets, houses, aspects, …) funcionam publicamente sem chave, com um limite de 30 pedidos / hora por IP. Se os pedidos vêm do teu servidor, envia o cabeçalho X-AstroWay-Site-URL e o limite passa a 300 pedidos / hora por site: detalhes.

Obtém uma chave API em 60 segundos

aw_test_demo_aaaa1111

Registar - grátis→

Para todos os endpoints de cálculo /v1/* (chart, synastry, transits, /reports, /tarot, etc.) - apenas X-Api-Key. Para operações do utilizador /v1/me/* (GET /me, DELETE /me/account) - Bearer JWT emitido por /v1/auth/login. OAuth e cookies de sessão não são usados na API pública. Os dicionários de referência /v1/reference/* - sem chave, gratuitos (tabelas de lookup canónicas).

Formato da chave

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

• aw_live_: produção, gasta créditos do saldo
• aw_test_: sandbox, os pedidos devolvem uma resposta stub (ou um cálculo real mínimo), não gastam créditos, aparecem separados no dashboard
• Depois do prefixo: 32 caracteres base62, criptograficamente aleatórios
• A chave é mostrada por extenso apenas uma vez, na criação. Depois, no dashboard, só aparecem os primeiros e os últimos 4 caracteres.

Cabeçalho do pedido

POST /v1/chart HTTP/1.1
Host: api.astroway.info
X-Api-Key: aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
Content-Type: application/json

Coleção Postman

Se o Postman te dá mais jeito do que curl ou um SDK, há uma coleção pronta com todos os 771 endpoints, dividida em 55 pastas segundo as tags do OpenAPI, com exemplos de pedidos já preenchidos. A autenticação está configurada ao nível da coleção: colas a chave na variável apiKey uma vez e todos os pedidos a usam.

• Documentação publicada: documenter.getpostman.com/view/54689779/2sBXqNmy3n
• Workspace público: postman.com/astroway-info/astroway-api
• Descarregar JSON: astroway-api.json (≈ 5 MB) - importa diretamente no Postman ou no Insomnia

A coleção é gerada automaticamente a partir da especificação OpenAPI - é atualizada a cada deploy.

Criar e gerir chaves

Através do dashboard:

• api.astroway.info/dashboard/keys
• Podes ter até 10 chaves ativas por conta em simultâneo
• Cada chave tem um nome, o campo name (por exemplo production-backend, ci-tests, local-dev)

Através da API (para integrações self-service):

cURL

curl -X POST https://api.astroway.info/v1/keys \
  -H "X-Api-Key: aw_live_master_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-tests", "mode": "test"}'

TypeScript

// Equivalent via @astroway/sdk: aw.client.POST('/keys', { body: { name, mode } })
const r = await fetch('https://api.astroway.info/v1/keys', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.ASTROWAY_MASTER_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'ci-tests', mode: 'test' }),
});

const { data: created } = await r.json();
console.log(created.api_key); // shown once - store it now

Python

# Equivalent via `astroway` (PyPI): aw.post('/keys', body={'name': ..., 'mode': ...})
import os, requests

r = requests.post(
    'https://api.astroway.info/v1/keys',
    headers={'X-Api-Key': os.environ['ASTROWAY_MASTER_KEY']},
    json={'name': 'ci-tests', 'mode': 'test'},
)
created = r.json()['data']
print(created['api_key'])  # shown once - store it now

PHP

<?php
use GuzzleHttp\Client;

$aw = new Client(['base_uri' => 'https://api.astroway.info/v1/']);
$r = $aw->post('keys', [
    'headers' => ['X-Api-Key' => getenv('ASTROWAY_MASTER_KEY')],
    'json' => ['name' => 'ci-tests', 'mode' => 'test'],
]);

$created = json_decode($r->getBody(), true)['data'];
echo $created['api_key']; // shown once - store it now

Dica

A chave master (a que criaste no dashboard) pode gerir outras chaves através de /v1/keys. As chaves normais não podem. Isto está definido no scope da chave.

Chaves para o navegador

Uma chave típica é server-only: se um pedido com ela traz o cabeçalho Origin ou Referer, recebe 403 ORIGIN_FORBIDDEN. É intencional, e é isto que apanha uma chave deixada por engano no frontend.

Quando um widget ou uma página têm de chamar a API a partir do navegador, a chave é criada logo com uma política de origem. O campo origin_restriction em POST /v1/keys:

type	O que é permitido	Quando usar
server-only (por omissão)	apenas pedidos sem Origin nem Referer	backend, cron, CI
public	apenas os hosts listados, e o pedido tem de trazer a origem	widget ou página no teu domínio, chave no código-fonte
allowlist	o mesmo que public	grafia obsoleta: continua a ser aceite, mas já não aparece em openapi.json

curl -X POST https://api.astroway.info/v1/keys \
  -H "X-Api-Key: aw_live_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "site-widget",
    "origin_restriction": {
      "type": "public",
      "allowed_origins": ["example.com", "*.example.com"]
    },
    "credits_cap_cycle": 20000,
    "allowed_endpoints": ["chart", "public/*"]
  }'

Regras de correspondência, verificadas em produção:

• Até 20 hosts por chave. O esquema (https://) e a porta são ignorados, maiúsculas e minúsculas não importam.
• www. é removido do host de entrada, por isso example.com cobre também www.example.com. Não é preciso acrescentar a forma com www., não muda nada.
• *.example.com cobre subdomínios (app.example.com), mas não o próprio example.com. O domínio raiz é listado numa linha à parte, como no exemplo acima.
• Um host fora da lista recebe 403 ORIGIN_NOT_ALLOWED com o próprio host no campo incoming_origin, para se ver que linha falta.
• Referer conta tanto como Origin: o navegador envia-o onde Origin não existe.

Cuidado

type: "public" cria uma chave da classe pk_, e para ela a regra é a inversa: um pedido sem Origin e sem Referer recebe 403 ORIGIN_REQUIRED, em vez de passar como pedido de servidor. Por isso a lista é obrigatória logo na criação, senão chega um 400. Até 2026-09-12 este modo significava “qualquer origin”; a 2026-09-24 as últimas chaves desse tipo receberam uma lista montada a partir do seu próprio tráfego, ou passaram a server-only, se não tinham pedidos de navegador. Uma origin da lista de uma chave pk_ recebe também access-control-allow-origin nas respostas de /v1/*, por isso a página consegue lê-las. A política é visível em GET /v1/keys no campo origin_restriction.

Alterar a lista de uma chave já criada

PATCH /v1/keys/{id} reescreve a lista sem mexer na chave em si. A permissão de acesso é a mesma que em POST /v1/keys acima; no dashboard é a opção “Alterar origem” no menu da chave.

curl -X PATCH https://api.astroway.info/v1/keys/433 \
  -H "X-Api-Key: aw_live_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_restriction": {
      "type": "public",
      "allowed_origins": ["example.com", "*.example.com"]
    }
  }'

A nova lista vale logo a partir do pedido seguinte: a cache da chave é limpa durante a escrita, não é preciso esperar um minuto. A string da chave não muda, por isso não é preciso voltar a publicar nem a página nem o backend. Depois de POST /v1/keys/{id}/rotate a lista mantém-se, e o valor antigo da chave deixa de funcionar de imediato.

A classe da chave não é editável, porque está escrita na própria chave:

Tentativa	Resposta
tornar uma pk_ server-only	400: a classe faz parte da chave, é preciso revogá-la e criar uma nova
dar uma lista de domínios a uma aw_	400: a chave de navegador é outra classe, cria-se como public
pk_ com lista vazia	400: uma chave sem lista rejeitaria todos os pedidos

Orçamento de créditos por chave

Os créditos são partilhados por toda a conta, por isso uma chave pode gastá-los todos. Para uma chave de backend isso é normal, para uma chave no código-fonte de uma página não: a lista de domínios diz de onde se pode chamar, mas não diz quanto isso pode custar.

credits_cap_cycle no mesmo PATCH /v1/keys/{id} limita exatamente esta chave:

curl -X PATCH https://api.astroway.info/v1/keys/433 \
  -H "X-Api-Key: aw_live_master_key" \
  -H "Content-Type: application/json" \
  -d '{"credits_cap_cycle": 5000}'

null remove o limite. 0 significa uma chave com a qual não se pode gastar nada: uma forma de estacionar a chave sem a revogar. O contador é o mesmo que o dos créditos e é reposto a zero juntamente com o ciclo do plano.

Quando uma chave esgota o seu orçamento, chega 429 KEY_BUDGET_EXHAUSTED, mesmo que a conta ainda tenha créditos, e mesmo num plano com overage: um orçamento que se pode ultrapassar pagando não é um orçamento. Enquanto houver orçamento definido, cada resposta traz X-Key-Budget-Limit e X-Key-Budget-Remaining.

Âmbito de endpoints

Uma chave sem âmbito chama tudo o que o plano inclui. allowed_endpoints restringe-a a uma lista de caminhos: exatos (chart) ou um namespace (embed/*). É uma terceira restrição independente: a lista de domínios diz de onde, o orçamento quanto, o âmbito o quê.

curl -X PATCH https://api.astroway.info/v1/keys/433 \
  -H "X-Api-Key: aw_live_master_key" \
  -H "Content-Type: application/json" \
  -d '{"allowed_endpoints": ["embed/*", "public/moon-phase"]}'

null remove a restrição. Uma lista vazia não é aceite: seria lida tanto como “tudo” como “nada”. Os caminhos escrevem-se relativos a /v1, sem barra inicial, sem distinção de maiúsculas.

Uma chamada fora da lista recebe 403 ENDPOINT_NOT_IN_SCOPE, e details indica a própria lista, para não ser preciso adivinhar. O âmbito aplica-se às duas classes de chaves e a /v1/public/* e /v1/embed/* tal como ao resto. As leituras de serviço não estão isentas dele, ao contrário do que acontece com os créditos: uma chave restrita a embed/* não consegue ler nem as suas próprias estatísticas. É intencional, porque uma chave no código-fonte de uma página não deve revelar ao visitante os gastos da conta, e isso não impede gerir a chave: o dashboard usa a sessão, não a chave.

Boas práticas

1. Não ponhas uma chave server-only no frontend

Uma chave típica é um segredo de backend. Se acabar num JS que corre no navegador do utilizador, fica visível nas DevTools e vai vazar. É exatamente por isso que uma chave destas responde 403 ORIGIN_FORBIDDEN a qualquer pedido com Origin ou Referer.

Se mesmo assim for preciso chamar a partir do navegador, isso faz-se não com uma chave normal, mas com uma chave separada, criada com origin_restriction.type: "public": chaves para o navegador. Uma chave destas tem o prefixo pk_, também é visível nas DevTools, e é essa a ideia - o seu valor está limitado à lista dos teus domínios, e ela rejeita pedidos sem origem.

Correto: o teu backend guarda a chave, o frontend chama o teu backend, o teu backend chama a AstroWay API.

Errado:

// DO NOT DO THIS
fetch('https://api.astroway.info/v1/chart', {
  headers: { 'X-Api-Key': 'aw_live_...' }, // visible in browser
});

2. Variáveis de ambiente, não hardcode

# .env (in .gitignore)
ASTROWAY_API_KEY=aw_live_...

// in code
const key = process.env.ASTROWAY_API_KEY;
if (!key) throw new Error('ASTROWAY_API_KEY is not set');

3. Chaves separadas para ambientes diferentes

• production-backend: produção
• staging-backend: staging
• ci-tests: pipeline de CI/CD
• local-dev-maksym: desenvolvimento local de cada programador

Se uma chave for comprometida, revogas só essa, as outras continuam a funcionar.

4. Rotação

A frequência recomendada é uma vez a cada 90 dias. Ou imediatamente, se houver suspeita de fuga.

Rotação sem downtime:

1. Cria uma nova chave com o mesmo name + -v2
2. Coloca-a em produção (em paralelo com a antiga)
3. Confirma que o uso está a passar para a nova chave (dashboard)
4. Revoga a antiga

5. Monitorização do uso

O dashboard mostra os pedidos de cada chave em separado. Se de repente uma chave começar a fazer 10× mais pedidos do que o habitual, é sinal para verificar.

Podes configurar um alerta: Settings → Notifications → Alert when daily credits > X.

Erros de autenticação

Código	Significado
401 Unauthorized	O cabeçalho X-Api-Key está ausente ou a chave é inválida
403 Forbidden	A chave é válida, mas não tem scope para esta ação (por exemplo, uma chave normal a tentar gerir outras chaves)
402 Payment Required	Os créditos acabaram (no Free) ou a subscrição está inativa
429 Too Many Requests	Rate limit excedido (10/60/300 req/min consoante o plano)

Exemplo de 401:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "request_id": "8aec43e9bc749b37e998a489bbad1757"
  }
}

Modo sandbox

As chaves com o prefixo aw_test_ funcionam em sandbox:

• Não gastam créditos
• Devolvem uma resposta stub ou um cálculo real mínimo
• Não afetam as estatísticas de produção
• Endpoints disponíveis: os mesmos

Útil para CI/CD, testes e2e e desenvolvimento local. Cria-se no dashboard com um clique.

A seguir

• Créditos e limites: como funcionam a faturação e o rate limiting
• Erros: lista completa de códigos de erro