Clés API — tnea_ & tnsr_¶

NumerologyAPI utilise deux familles de clés API. Les deux se ressemblent, sont générées avec le même format sécurisé de 80 caractères et s'authentifient avec le même en-tête X-API-Key — mais elles sont comptabilisées différemment et sont destinées à des produits différents.

1. Format et sécurité des clés¶

Chaque clé fait exactement 80 caractères :

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Le préfixe de 4 caractères identifie le type de clé ; les 75 caractères restants sont générés à partir d'une source aléatoire cryptographiquement sécurisée.
• Les clés sont stockées côté serveur sous forme de hachage SHA-256. La clé en clair n'est affichée qu'une seule fois, lors de sa création.
• Si une clé est exposée, faites-la pivoter immédiatement depuis le tableau de bord.

2. Clés de plateforme (tnea_)¶

Les clés de plateforme sont les clés standard pour intégrer NumerologyAPI dans votre propre produit — sites web, applications mobiles et services côté serveur.

Authentification¶

Envoyez la clé sur chaque requête avec l'en-tête X-API-Key :

curl --request GET \
  --url "https://api.numerologyapi.com/api/v1/life_path?birth_year=1990&birth_month=5&birth_day=15" \
  --header "x-api-key: tnea_YOUR_API_KEY"

Comptabilisation¶

Les appels facturables /api/v1 sont déduits du portefeuille de crédits de votre organisation (paiement à l'usage). Vous pouvez recharger le portefeuille à tout moment depuis le tableau de bord.

Règle de canal : les clés de plateforme ne doivent pas envoyer l'en-tête X-Numora-Client. Son envoi renvoie 403 — cet en-tête est réservé au canal de bureau.

3. Clés Numora Studio (tnsr_)¶

Les clés Numora Studio authentifient l'application de bureau Numora Studio (macOS/Windows) utilisée par les praticiens pour générer des rapports clients. Elles sont les jumelles des clés de plateforme, avec un format identique, mais elles sont facturées sur l'allocation du forfait Numora Studio de l'organisation au lieu des crédits de plateforme.

Provisionnement¶

Une clé tnsr_ est créée soit :

• via le flux de connexion de l'application de bureau (la page de consentement du navigateur provisionne une clé automatiquement), soit
• manuellement sur la page Clés API du tableau de bord (/api-keys).

Signature de canal (obligatoire)¶

Chaque appel effectué avec une clé tnsr_ doit inclure l'en-tête de canal de bureau :

Application côté serveur :

• Clé tnsr_ sans X-Numora-Client → 403.
• Clé tnea_ avec X-Numora-Client → 403.

Comptabilisation¶

• Les appels facturables /api/v1 sont déduits de l'allocation du forfait Numora Studio de l'organisation (un pool partagé unique entre toutes les clés tnsr_ de l'organisation).
• Un basculement sur les crédits existe pour chaque clé tnsr_ : lorsque l'allocation du forfait est épuisée, la clé peut basculer sur les crédits de plateforme de l'organisation (désactivé par défaut).
• Si l'allocation est épuisée et qu'aucun basculement n'est activé, les appels renvoient 429.

Verrouillage d'appareil (facultatif)¶

Une clé tnsr_ peut être verrouillée sur des appareils enregistrés. Avec le verrouillage activé, chaque requête doit comporter un X-Numora-Device-Id enregistré auprès de l'organisation ; les appareils non enregistrés sont rejetés avec 403.

Points de terminaison exclusifs au bureau¶

Certains points de terminaison sont réservés au canal de bureau et renvoient 403 pour les clés tnea_ :

• POST /api/v1/numora/report-bundle — rapport client complet en un seul appel
• POST /api/v1/numora/order — flux d'achat du forfait/allocation intégré à l'application
• POST /api/v1/numora/devices/register — enregistrer une installation de bureau
• GET /api/v1/numora/studio-status — soldes et compteurs de quota du bureau

Astuce : les réponses facturables incluent également les en-têtes X-Remaining-Credits et X-Remaining-Tokens pour suivre vos soldes en temps réel sans appels supplémentaires.

4. Gestion des clés (tableau de bord)¶

La page Clés API du tableau de bord (/api-keys) est le centre de contrôle des deux types de clés.

Rôles : les rôles admin et developer peuvent créer et gérer les clés. finance ne peut pas créer de clés API de production. Les opérations financières (achats de forfaits, rechargements) sont limitées à admin et finance.

Clés multiples : les organisations peuvent détenir de nombreuses clés des deux types — par exemple une clé tnsr_ par praticien ou par installation de bureau. Les allocations sont partagées par organisation, donc les clés n'« entrent jamais en concurrence » pour leur propre solde.

5. Bonnes pratiques¶

• Traitez les clés comme des mots de passe. Ne les intégrez jamais dans du code côté client, des dépôts publics ou des journaux.
• Utilisez des variables d'environnement ou un gestionnaire de secrets dans votre backend.
• Faites pivoter immédiatement si une clé est compromise ou si un membre de l'équipe quitte l'organisation.
• Utilisez une clé tnsr_ par installation de bureau pour simplifier la gestion des appareils et la révocation.
• Activez le verrouillage d'appareil pour les organisations à haute exigence de sécurité.
• Surveillez l'utilisation dans le tableau de bord pour détecter rapidement les pics inattendus.

6. Questions fréquentes¶

Une clé tnsr_ peut-elle appeler les points de terminaison de plateforme standard ? Oui. Les clés Numora Studio authentifient l'ensemble de la surface /api/v1 ; ces appels sont facturés sur l'allocation du forfait Numora Studio.

Une clé tnea_ peut-elle appeler les points de terminaison /numora/* exclusifs au bureau ? Non. Les points de terminaison exclusifs au bureau renvoient 403 pour les clés de plateforme.

Pourquoi est-ce que j'obtiens 403 lors d'un appel avec ma clé tnsr_ ? Il s'agit très probablement d'un en-tête X-Numora-Client manquant ou d'un identifiant d'application qui ne correspond pas. Vérifiez que chaque requête inclut X-Numora-Client: numora-studio/<version>.

Pourquoi est-ce que j'obtiens 403 avec ma clé tnea_ ? Les clés de plateforme ne doivent pas comporter l'en-tête X-Numora-Client — retirez-le.

Que se passe-t-il lorsque mon allocation est épuisée ? Les appels facturables renvoient 429 sauf si le basculement sur les crédits est activé sur votre clé tnsr_ (ou si vous rechargez votre portefeuille de plateforme pour les clés tnea_).

En relation¶

• Démarrage rapide
• Tarifs
• Solutions Enterprise