Authentification et quotas

Obtenir une clé

La clé est gratuite. Une adresse e-mail a une seule clé active.

Sur la page Obtenir une clé API, tu donnes ton adresse e-mail.
Tu reçois un lien de connexion. Il ne sert qu’une fois et expire après 15 minutes.
La page que le lien ouvre affiche ta clé, une seule fois : le serveur n’en garde qu’une empreinte. Copie-la tout de suite.

La réponse est la même que l’adresse ait déjà une clé ou non. Au-delà de 3 liens par heure pour une même adresse, la demande est acceptée sans nouvel envoi.

Envoyer la clé

Les routes de vérification, GET /v1/check et POST /v1/check/batch, demandent la clé dans l’en-tête Authorization, avec le schéma Bearer (RFC 6750) :

GET /v1/check?q=armen.ltd HTTP/1.1
Authorization: Bearer ark_live_…

Les routes de référence, GET /v1/sources et GET /v1/signals, sont publiques : elles ne demandent pas de clé.

Une clé fait 45 caractères : ark_live_, 30 caractères aléatoires et une somme de contrôle de 6 caractères. Les outils de détection de secrets la reconnaissent à cette forme. Garde-la côté serveur, dans une variable d’environnement : jamais dans ton dépôt, dans une URL ou dans du code exécuté par un navigateur.

Quand la clé est refusée, la réponse est une erreur 401 :

missing_api_key : pas d’en-tête Authorization au schéma Bearer ;
invalid_api_key : clé mal formée, inconnue ou révoquée.

Si l’API ne peut pas vérifier la clé pour le moment, elle répond authentication_unavailable (503) plutôt que de servir la requête sans contrôle. Ta clé n’est pas en cause : réessaie plus tard.

Faire tourner la clé

Pour changer de clé, par exemple si elle a fuité, demande un nouveau lien avec la même adresse. Quand la page du lien te donne la nouvelle clé, l’ancienne est révoquée aussitôt : il n’y a pas de période où les deux marchent. Remplace la clé dans ta configuration dès que tu l’as, les requêtes qui portent l’ancienne reçoivent invalid_api_key.

Quotas

Chaque quota a un nom, sa politique, que les en-têtes de réponse indiquent. Le quota entier peut être dépensé d’un coup, puis il revient au même rythme sur la minute.

key : 60 requêtes par minute et par clé, sur GET /v1/check et POST /v1/check/batch.
ip : 30 requêtes par minute et par adresse du client (préfixe /64 en IPv6), sur GET /v1/sources et GET /v1/signals.
auth : 30 clés refusées par minute et par adresse du client, sur GET /v1/check et POST /v1/check/batch.

Chaque élément d’un lot POST /v1/check/batch compte pour une requête du quota key, qu’il soit valide ou non. Avec 10 requêtes restantes, un lot de 4 éléments en dépense 4 et laisse r=6 dans RateLimit. S’il reste moins de requêtes que d’éléments, le lot entier est refusé en 429 et ne dépense rien : un lot de 7 éléments est alors refusé, un lot de 6 passe.

Quand le quota auth est dépensé, les clés envoyées depuis cette adresse ne sont plus vérifiées : la réponse est 429, même pour une clé valide, jusqu’à ce qu’il revienne.

Les quotas ip et auth comptent par adresse : derrière une adresse partagée (un réseau d’entreprise derrière un NAT, ou le même préfixe /64 en IPv6), un autre poste peut dépenser le tien. Une clé valide reçoit alors elle aussi 429 du quota auth.

Ces valeurs sont celles du 04/11/2026. Chaque instance du serveur tient ses propres compteurs. Les en-têtes de chaque réponse donnent l’état du quota sur l’instance qui répond.

Lire les en-têtes

Une réponse comptée dans un quota porte deux en-têtes (draft-ietf-httpapi-ratelimit-headers-11). Relevés en production sur GET /v1/sources :

RateLimit-Policy: "ip";q=30;w=60
RateLimit: "ip";r=29;t=2

RateLimit-Policy : le nom de la politique, q requêtes permises par fenêtre de w secondes.
RateLimit : r requêtes encore permises maintenant ; t secondes avant qu’une requête de plus soit rendue, 0 quand le quota est entier.

Ralentis quand r approche de 0, plutôt que d’attendre la réponse 429.

La réponse 429

Au-delà du quota, l’API répond too_many_requests, avec l’en-tête Retry-After en secondes. RateLimit-Policy nomme le quota atteint. Relevé en production le 04/11/2026 :

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit: "ip";r=0;t=1
RateLimit-Policy: "ip";q=30;w=60
Retry-After: 1

{
  "type": "https://arnakoff.com/docs/erreurs/too_many_requests",
  "title": "Trop de requêtes",
  "status": 429,
  "detail": "Le quota de requêtes est atteint. Réessaie après le délai de l'en-tête Retry-After.",
  "instance": "tag:arnakoff.com,2026:request:afe296bb-8634-4919-bb51-cd6413a58253",
  "code": "too_many_requests"
}

Attends le nombre de secondes de Retry-After avant de renvoyer la requête. Pour un lot, Retry-After dit quand toutes ses requêtes seront revenues : il peut dépasser le t de RateLimit, qui ne compte qu’une requête. Tu peux aussi envoyer un lot plus petit. Pour auth, corrige d’abord la clé refusée : chaque nouveau refus dépense encore le quota.

Les routes, leurs en-têtes et leurs erreurs sont dans la référence de l’API.