Authentification

Presque toutes les requêtes vers l’API AstroWay sont authentifiées via l’en-tête X-Api-Key. Exceptions : 14 endpoints /v1/reference/* (signs, planets, houses, aspects, …) fonctionnent publiquement sans clé avec une limite de 30 requêtes / heure par IP. Si ton serveur effectue les requêtes, envoie l’en-tête X-AstroWay-Site-URL et la limite passera à 300 requêtes / heure par site : détails.

Pour tous les endpoints de calcul /v1/* (chart, synastry, transits, /reports, /tarot, etc.) - uniquement X-Api-Key. Pour les opérations utilisateur /v1/me/* (GET /me, DELETE /me/account) - Bearer JWT, émis via /v1/auth/login. OAuth/session-cookies ne sont pas utilisés sur l’API publique. Les dictionnaires de référence /v1/reference/* - sans clé, gratuits (tables de correspondance canoniques).

Format de la clé

aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR
aw_test_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR

aw_live_ : production, déduit les crédits du solde
aw_test_ : sandbox, les requêtes renvoient une réponse stub (ou un calcul réel minimal), ne déduisent pas de crédits, marquées séparément dans le dashboard
Après le préfixe : 32 caractères base62, cryptographiquement aléatoires
La clé est affichée en clair une seule fois lors de sa création. Ensuite, dans le dashboard, seuls les 4 premiers et derniers caractères sont visibles.

En-tête de la requête

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

Collection Postman

Si tu préfères Postman à curl/SDK, une collection prête à l’emploi est disponible avec tous les 771 endpoints, réorganisée en 55 dossiers par tags OpenAPI, avec des exemples de requêtes pré-remplis. L’authentification est configurée au niveau de la collection : tu insères la clé dans la variable apiKey une seule fois, et toutes les requêtes l’utilisent.

Published docs: documenter.getpostman.com/view/54689779/2sBXqNmy3n
Public workspace: postman.com/astroway-info/astroway-api
Télécharger le JSON : astroway-api.json (≈ 5 Mo) - importe-le directement dans Postman ou Insomnia

Collection auto-générée à partir de la spécification OpenAPI - mise à jour à chaque déploiement.

Création et gestion des clés

Via le dashboard :

api.astroway.info/dashboard/keys
Tu peux avoir jusqu’à 10 clés actives par compte simultanément
Chaque clé a un nom, le champ name (par exemple production-backend, ci-tests, local-dev)

Via l’API (pour les intégrations en self-service) :

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"}'

// 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

# 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
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

Clés pour le navigateur

Une clé typique server-only : si une requête avec celle-ci contient l’en-tête Origin ou Referer, elle reçoit un 403 ORIGIN_FORBIDDEN. C’est intentionnel, et c’est ce qui intercepte une clé accidentellement laissée dans le frontend.

Lorsqu’un widget ou une page doit accéder à l’API depuis le navigateur, la clé est créée immédiatement avec une politique d’origine. Le champ origin_restriction dans POST /v1/keys :

`type`	Ce qui est autorisé	Quand l’utiliser
`server-only` (par défaut)	uniquement les requêtes sans `Origin` et `Referer`	backend, cron, CI
`public`	uniquement les hôtes listés, et la requête doit contenir l’origine	widget ou page sur ton domaine, clé dans le code source
`allowlist`	identique à `public`	écriture obsolète : toujours acceptée, mais ne figure plus dans `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/*"]
  }'

Règles de correspondance, vérifiées en production :

Jusqu’à 20 hôtes par clé. Le schéma (https://) et le port sont ignorés, la casse n’a pas d’importance.
www. est supprimé de l’hôte entrant, donc example.com couvre également www.example.com. Il n’est pas nécessaire d’ajouter séparément la forme avec www., cela ne change rien.
*.example.com couvre les sous-domaines (app.example.com), mais pas example.com lui-même. L’apex est listé sur une ligne séparée, comme dans l’exemple ci-dessus.
Un hôte non listé reçoit un 403 ORIGIN_NOT_ALLOWED avec l’hôte lui-même dans le champ incoming_origin, pour montrer quelle ligne est manquante.
Referer est traité de la même manière que Origin : le navigateur l’envoie là où Origin est absent.

type: "public" crée une clé de classe pk_, et pour celle-ci, la règle est inverse : une requête sans Origin et sans Referer reçoit un 403 ORIGIN_REQUIRED, au lieu de passer comme une requête serveur. Par conséquent, lors de la création, trois éléments sont obligatoires : la liste des domaines, le budget credits_cap_cycle et la portée allowed_endpoints (tous deux décrits ci-dessous). Sans l’un d’eux, un 400 est renvoyé, et une clé pk_ à laquelle il manque un budget ou une portée est rejetée partout avec un 403 PUBLISHABLE_KEY_UNBOUNDED. La clé dans le code de la page peut être lue par n’importe qui, elle n’est donc jamais illimitée. Avant le 2026-09-12, ce mode signifiait “toute origine” ; le 2026-09-24, les dernières clés de ce type ont reçu une liste collectée à partir de leur propre trafic, ou sont devenues des clés serveur si elles n’avaient pas de requêtes navigateur. L’origine de la liste de la clé pk_ reçoit également access-control-allow-origin dans les réponses /v1/*, de sorte que la page peut les lire. La politique est visible dans GET /v1/keys dans le champ origin_restriction.

Modifier la liste d’une clé existante

PATCH /v1/keys/{id} réécrit la liste sans toucher à la clé elle-même. Le droit d’accès est le même que pour POST /v1/keys ci-dessus ; dans le tableau de bord, c’est l’option “Modifier l’origine” dans le menu de la clé.

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"]
    }
  }'

La nouvelle liste est effective dès la prochaine requête : le cache de la clé est réinitialisé lors de l’écriture, il n’est pas nécessaire d’attendre une minute. La chaîne de caractères de la clé elle-même ne change pas, il n’est donc pas nécessaire de redéployer la page ou le backend. Après POST /v1/keys/{id}/rotate, la liste est conservée, et l’ancienne valeur de la clé cesse de fonctionner immédiatement.

La classe de la clé n’est pas modifiable, car elle est enregistrée dans la clé elle-même :

Tentative	Réponse
Rendre `pk_` `server-only`	`400` : la classe fait partie de la clé, tu dois la révoquer et en créer une nouvelle
Donner une liste de domaines à `aw_`	`400` : une clé de navigateur est une classe différente, elle est créée comme `public`
`pk_` avec une liste vide	`400` : une clé sans liste rejetterait chaque requête
`pk_` sans budget ni portée (`null`)	`400` : une clé pour le navigateur est toujours limitée par les deux, tu peux les modifier, mais pas les supprimer

Budget de crédits par clé

Les crédits sont partagés sur l’ensemble du compte, donc une seule clé peut tous les dépenser. C’est normal pour une clé de backend, mais pas pour une clé dans le code source d’une page : la liste des domaines indique d’où l’on peut se connecter, mais pas combien cela peut coûter.

credits_cap_cycle dans le même PATCH /v1/keys/{id} limite spécifiquement cette clé :

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 supprime la restriction (sauf pour la clé pk_, pour laquelle le budget peut être modifié mais pas supprimé). 0 signifie une clé qui ne peut rien dépenser : une façon de “garer” une clé sans la révoquer. Le compteur est le même que celui des crédits, et il est réinitialisé avec le cycle de facturation.

Quand une clé atteint son budget, un 429 KEY_BUDGET_EXHAUSTED est renvoyé, même s’il reste des crédits sur le compte, et même avec un plan avec dépassement : un budget qui peut être dépassé contre paiement n’est pas un budget. Tant que le budget est défini, chaque réponse contient X-Key-Budget-Limit et X-Key-Budget-Remaining.

Portée des endpoints

Une clé sans portée appelle tout ce qui est inclus dans le plan. allowed_endpoints le restreint à une liste de chemins : exacts (chart) ou d’espaces de noms (embed/*). C’est la troisième restriction indépendante : la liste des domaines indique d’où, le budget combien, la portée quoi exactement.

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 supprime la restriction (sauf pour la clé pk_, pour laquelle la portée est obligatoire). Une liste vide n’est pas acceptée : elle serait interprétée à la fois comme “tout” et comme “rien”. Les chemins sont écrits par rapport à /v1, sans le slash initial, la casse n’a pas d’importance.

Un appel en dehors de la liste reçoit un 403 ENDPOINT_NOT_IN_SCOPE, et details nomme la liste elle-même pour éviter d’avoir à deviner. La portée s’applique aux deux classes de clés et à /v1/public/* et /v1/embed/* de la même manière qu’au reste. Les lectures de service ne sont pas exemptées, contrairement aux crédits : une clé restreinte à embed/* ne lira pas ses propres statistiques. C’est intentionnel, car une clé dans le code source d’une page ne doit pas révéler les dépenses du compte au visiteur, et cela n’empêche pas de gérer la clé : le dashboard utilise une session, pas une clé.

Bonnes pratiques

1. Ne place pas de clé server-only dans le frontend

Une clé typique est un secret de niveau backend. Si elle se retrouve dans le JS exécuté dans le navigateur de l’utilisateur, elle sera visible dans les DevTools et fuira. C’est pourquoi une telle clé répond 403 ORIGIN_FORBIDDEN à toute requête avec Origin ou Referer.

Si tu dois tout de même faire des requêtes depuis le navigateur, cela se fait non pas avec une clé ordinaire, mais avec une clé séparée, créée avec origin_restriction.type: "public" : clés pour le navigateur. Une telle clé a le préfixe pk_, elle est également visible dans les DevTools, et c’est là tout l’intérêt : sa valeur est limitée par la liste de tes domaines, et elle rejette toute requête sans origine.

Correct : ton backend détient la clé, le frontend interroge ton backend, ton backend interroge l’API AstroWay.

Incorrect :

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

2. Variables d’environnement, pas de 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. Clés séparées pour différents environnements

production-backend : production
staging-backend : staging
ci-tests : pipeline CI/CD
local-dev-maksym : développement local de chaque développeur

Si une clé est compromise, révoque-la spécifiquement, les autres continueront de fonctionner.

4. Rotation

Fréquence recommandée : une fois tous les 90 jours. Ou immédiatement, en cas de suspicion de fuite.

Rotation sans interruption :

Crée une nouvelle clé avec le même name + -v2
Déploie-la en production (parallèlement à l’ancienne)
Assure-toi que l’utilisation se dirige vers la nouvelle clé (dashboard)
Révoque l’ancienne

5. Surveillance de l’utilisation

Le dashboard affiche les requêtes par clé séparément. Si une clé commence soudainement à faire 10 fois plus de requêtes que d’habitude, c’est un signal à vérifier.

Tu peux configurer une alerte : Settings → Notifications → Alert when daily credits > X.

Erreurs d’authentification

Code	Signification
`401 Unauthorized`	L’en-tête `X-Api-Key` est absent ou la clé est invalide
`403 Forbidden`	La clé est valide, mais n’a pas la portée pour cette action (par exemple, une clé ordinaire tente de gérer d’autres clés)
`403 PUBLISHABLE_KEY_UNBOUNDED`	Clé `pk_` sans budget `credits_cap_cycle` ou sans portée `allowed_endpoints` : définis les deux dans les paramètres de la clé
`402 Payment Required`	Crédits épuisés (sur Free) ou abonnement inactif
`429 Too Many Requests`	Limite de débit dépassée (10/60/300 req/min selon le plan)

Exemple de 401 :

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

Mode Sandbox

Les clés avec le préfixe aw_test_ fonctionnent en mode sandbox :

Ne déduisent pas de crédits
Renvoient une réponse stub ou un calcul réel minimal
N’affectent pas les statistiques de production
Endpoints disponibles : les mêmes

Utile pour le CI/CD, les tests e2e et le développement local. Créé via le dashboard en un clic.

Suite

Crédits et limites : fonctionnement de la facturation et du rate limiting
Erreurs : liste complète des codes d’erreur

Utile?

Proposer une modification

Dernière mise à jour : 4 oct. 2026