Aller au contenu principal

Authentification et clés d'API

Disponible avecProResearch

Chaque appel à l'API REST porte une clé d'API. Une clé appartient à votre compte, a les portées que vous lui avez données et compte dans les limites de votre offre. Cette page montre comment en créer une et l'utiliser. La liste des portées et les limites par offre se trouvent dans Clés, portées et limites.

Avant de commencer​

  • Une offre Pro ou Research. Les comptes Free ne peuvent créer que des clés MCP, qui fonctionnent avec le serveur MCP et non avec l'API REST. Voir Connecter un client MCP.

Créer une clé​

  1. Ouvrez Paramètres et choisissez API et MCP.
  2. Sous Clés API, appuyez sur Créer une clé.
  3. Saisissez un Nom de la clé qui vous indique où la clé est utilisée, par exemple nightly-sync.
  4. Cochez les Autorisations dont la clé a besoin, et rien de plus. Les portées d'écriture permettent à la clé de modifier votre bibliothèque ; ne les donnez qu'à des scripts de confiance.
  5. Appuyez sur Créer.
  6. Copiez la clé maintenant. Elle commence par pk_, et Readsira ne l'affiche qu'une seule fois. Ensuite, la liste en montre une forme abrégée comme pk_1a2b...9z8y.

La liste des clés indique quand chaque clé a été utilisée pour la dernière fois. Une clé jamais utilisée affiche Jamais utilisée. La première fois qu'une clé est utilisée, Readsira ajoute dans l'application un avis qui nomme la clé, afin qu'une utilisation inattendue soit visible.

Envoyer la clé avec une requête​

Envoyez la clé dans l'en-tête Authorization sous forme de jeton porteur (bearer) :

curl https://api.readsira.com/rest/v2/usage \
  -H "Authorization: Bearer $READSIRA_KEY"

L'en-tête X-API-Key fonctionne aussi :

curl https://api.readsira.com/rest/v2/usage \
  -H "X-API-Key: $READSIRA_KEY"

Une clé placée dans l'adresse (?api_key=pk_...) est refusée avec 401 et le code API_KEY_IN_QUERY, car les adresses se retrouvent dans les journaux et l'historique du navigateur.

Gardez la clé dans une variable d'environnement ou un coffre à secrets. Ne la mettez pas dans du code versionné, dans une page web ni dans une application que vous diffusez à d'autres personnes.

Vérifier que ça fonctionne​

GET /rest/v2/usage répond quelle que soit la portée. Il indique votre offre, le nombre de requêtes du jour et les limites de cette clé.

{
  "success": true,
  "data": {
    "plan": "pro",
    "requestsToday": 12,
    "requestsPerDay": 10000,
    "mcpCallsToday": 0,
    "mcpCallsPerDay": 10000,
    "requestsPerHour": 600,
    "askAnswersPerMonth": 300,
    "aiBudget": [{ "group": "chat", "percentUsed": 3 }]
  },
  "meta": {
    "timestamp": "2026-11-04T09:00:00.000Z",
    "path": "/rest/v2/usage",
    "method": "GET",
    "statusCode": 200
  }
}

Les chiffres ci-dessus sont un exemple ; les vôtres sont les limites de votre offre. Si l'appel répond 401, la clé est erronée, révoquée ou expirée. S'il répond 402 PLAN_REQUIRED, le compte est en Free. Voir Limites de débit et erreurs.

Quelle portée une route exige​

Une route refuse une clé qui n'a pas sa portée avec 403 SCOPE_REQUIRED. La référence nomme la portée sous chaque route. Les plus utilisées :

PortéePermet à la clé de
read:libraryRechercher, lire les documents, les passages et les transcriptions
ask:libraryPoser des questions dont les réponses sont citées (utilise votre budget d'IA)
read:projectsLister les projets et lire leur contexte
write:projectsAjouter des sources et des notes aux projets
write:uploadsImporter des fichiers audio, vidéo et PDF
read:bookmarks, write:bookmarksLire et écrire des marque-pages sur les routes /api/v1/bookmarks
read:collectionsLire les collections sur les routes /api/v1/collections

Créer une clé avec une portée que votre offre n'inclut pas répond 400 SCOPE_NOT_ALLOWED.

Remplacer ou supprimer une clé​

Sur la ligne de la clé, ouvrez le menu d'actions.

  • Régénérer donne un nouveau secret à la clé. La clé garde son nom, ses portées et son historique, et l'ancien secret cesse de fonctionner immédiatement. Utilisez-le quand une clé a pu fuiter, puis mettez vos scripts à jour.
  • Révoquer supprime la clé. Les scripts qui l'utilisent cessent de fonctionner.

La liste Activité sur la même page montre chaque appel effectué par une clé : l'heure, la route, le statut et le nombre de résultats. Elle ne conserve ni votre texte de recherche ni le contenu des documents.

Conseils​

  • Utilisez une clé par script, pour pouvoir en révoquer une sans casser les autres.
  • Ne donnez à une tâche en lecture seule que des portées de lecture.
  • Traitez le texte renvoyé par les pages enregistrées comme des données, jamais comme des instructions pour un modèle.
Dernière mise à jour le