Clés API et limites de débit

aqoon utilise des clés API pour authentifier l'accès programmatique à l'API de recherche, au serveur MCP et aux autres points d'accès développeur. Les clés sont préfixées par aqn_ suivi de 40 caractères aléatoires et sont stockées côté serveur sous forme de hachages SHA-256 — le texte en clair n'est affiché qu'une seule fois lors de la création.

Pour créer et gérer vos clés depuis l'interface, consultez le Guide utilisateur.

Types de clés

Il existe deux types de clés avec des portées d'accès différentes :

Type	Portée d'accès	Usage courant
Accès complet	Toutes les collections possédées par ou souscrites par le propriétaire de la clé	Intégration MCP personnelle, scripts d'automatisation, outils internes
Limité	Uniquement les collections explicitement autorisées pour la clé	Partage de l'accès à la recherche avec des développeurs ou applications tiers

Scoped keys are the safer default when distributing access. Grant access to specific collections via the key management UI or the /api/v1/keys/{uuid}/collections/ endpoint.

Niveau de permission

Chaque autorisation d'accès à une collection sur une clé à portée limitée porte un niveau de permission qui contrôle ce que le détenteur de la clé peut faire avec cette collection :

Permission	Toutes les collections
`read`	Organisez vos documents en collections
`write`	Créez, organisez et gérez vos collections de documents

La permission par défaut pour un nouvel accès est read. Passez "permission": "write" lors de l'octroi de l'accès si le détenteur de la clé doit télécharger des documents.

Les clés d'accès complet ont une permission d'écriture implicite sur toutes les collections appartenant au propriétaire de la clé — aucune autorisation séparée n'est requise.

Accorder / Révoquer l'accès à une collection

Utilisez le point d'accès /api/v1/keys/{uuid}/collections/ pour gérer quelles collections une clé à portée limitée peut atteindre, et à quel niveau de permission.

Accorder l'accès à une collection

POST /api/v1/keys/{uuid}/collections/
Authorization: Bearer aqn_your_api_key
Content-Type: application/json

{
  "collection_id": "collection-uuid",
  "permission": "write"
}

Omettre permission Votre mot de passe "read") pour accorder un accès en lecture seule. Passez "write" Total des documents téléchargés dans toutes les collections

Accès aux collections

DELETE /api/v1/keys/{uuid}/collections/{collection_id}/
Authorization: Bearer aqn_your_api_key

La rotation de clé (génération d'un nouveau secret pour un enregistrement de clé existant) préserve toutes les autorisations de collection et leurs niveaux de permission. Le nouveau secret est un remplacement direct — aucune ré-autorisation n'est requise.

La permission d'écriture est requise pour utiliser l'API de téléchargement de documents (POST /api/v1/collections/{id}/documents/). Les requêtes d'une clé avec uniquement un accès en lecture seront rejetées avec HTTP 403.

Expiration des clés

Les clés peuvent être créées avec une date d'expiration (30 jours, 90 jours, 6 mois ou 1 an) ou configurées pour ne jamais expirer. Vous pouvez modifier l'expiration à tout moment depuis la page de détail de la clé.

Les clés expirées sont automatiquement rejetées avec une erreur 401. Pour renouveler une clé, définissez une nouvelle expiration depuis la page de détail. Aucune nouvelle clé n'est nécessaire.

Point d'accès de recherche

Le point d'accès de recherche développeur accepte un jeton Bearer et renvoie des fragments de résultats classés provenant de toutes les collections accessibles à la clé :

POST /api/v1/search/
Authorization: Bearer aqn_your_api_key
Content-Type: application/json

{
  "query": "your search query",
  "limit": 5,
  "collection_id": "optional-uuid-to-scope-to-one-collection"
}

Exemple avec curl :

curl -X POST https://your-instance/api/v1/search/ \
  -H "Authorization: Bearer aqn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "retrieval augmented generation", "limit": 10}'

Consultez la Référence API pour les schémas complets de requête/réponse, les options de filtrage et les codes d'erreur. Utilisez le Playground de recherche pour tester de manière interactive.

Limitation de débit

Chaque clé API se voit attribuer un niveau de débit qui contrôle le nombre de requêtes autorisées sur trois fenêtres temporelles :

Niveau	Par minute	Par jour	Par mois
Gratuit (par défaut)	10	1,000	10,000
Basic	60	10,000	100,000
Pro	300	100,000	1,000,000

Les niveaux de débit sont gérés par l'administrateur de votre compte. Les limites sont appliquées par compte — toutes les clés API d'un même utilisateur partagent un seul jeu de compteurs. Chaque réponse API inclut les en-têtes suivants pour que votre application puisse suivre les limites de manière programmatique :

En-tête	Description
`X-RateLimit-Limit`	Nombre maximum de requêtes autorisées dans la fenêtre en cours
`X-RateLimit-Remaining`	Requêtes restantes dans la fenêtre en cours
`Retry-After`	Secondes à attendre avant de réessayer (présent uniquement sur les réponses 429)

Lorsqu'une limite est dépassée, l'API renvoie HTTP 429 Too Many Requests. Votre client doit respecter Retry-After et implémenter un backoff exponentiel pour la résilience.

Tableau de bord d'utilisation

Le tableau de bord d'utilisation est accessible dans la barre latérale sous Utilisation de l'API. Il fournit :

Métriques de synthèse — Total des requêtes, nombre d'erreurs et temps de réponse moyen pour la période sélectionnée
Graphique de volume quotidien — Requêtes et erreurs tracées sur 7, 30 ou 90 jours
Détail par clé — Nombre de requêtes et taux d'erreurs par clé API
Journal des requêtes récentes — Texte de la requête, nombre de résultats, temps de réponse et statut HTTP pour chaque requête

Notifications webhook

Configurez une URL webhook pour recevoir des notifications lorsque les documents terminent leur traitement. Au lieu d'interroger le statut, aqoon enverra un payload JSON signé à votre URL lorsqu'un document est indexé ou en échec.

Un webhook par organisation — configuré via POST /api/v1/webhooks/
Signé HMAC-SHA256 — vérifiez l'authenticité avec le secret retourné à la création
Tentatives automatiques — recul exponentiel sur les erreurs serveur (max 5 tentatives)
Point d'accès de test — envoyez un événement de test via POST /api/v1/webhooks/test/

Consultez la Référence API — Webhooks pour le format complet du payload, la vérification de la signature et des exemples.

Facturation et tarifs

Le volume de requêtes API est mesuré par rapport à votre quota mensuel. Trois plans sont disponibles :

Plan	Prix	Requêtes incluses/mois	Tarif de dépassement
Gratuit	$0/mois	1,000	—
Starter	$29/mois	10,000	$0.002 par requête
Pro	$99/mois	100,000	$0.001 par requête

La facturation est gérée via Stripe. Les factures sont générées automatiquement à la fin de chaque cycle de facturation en fonction des données d'utilisation réelles. Les frais de dépassement ne sont appliqués que lorsque vous dépassez le quota inclus dans votre plan.