# Authentification de l'API Choisissez OAuth ou un transfert de secret d'environnement délimité selon le client et la surface d'API. - Canonical: https://docs.xmemo.dev/fr/docs/api/authentication - Locale: fr-FR - Content-Locale: fr-FR - Canonical-Content-Digest: 2ccb101521e35878569be22c158ebf3f733f976c32f1b7952809dc29ffb5dba5 - Edition-Digest: 5163fd72f2c655a1106bf6a89d142f174a1bb44b6444f4db9ce17f8984d398ba - Source-Revision: sha256:0f4e5aaa7eba4f6a045f2818119002c0ddba188a30db4cee7ebfd8a2164d3e96 ## Deux surfaces authentifiées Le point de terminaison MCP hébergé et l'API REST s'authentifient différemment. Choisissez celle qui correspond au client que vous raccordez, et ne placez jamais d'identifiant dans une configuration publique ou une URL générée. - MCP — OAuth lorsque le client le prend en charge, sinon Authorization: Bearer ${XMEMO_KEY}. - Plan de données REST — X-API-Key: (Authorization: Bearer est également accepté par le serveur). POST /v1/agents/temporary-register autorise l'enregistrement anonyme selon ses conditions d'intégration et son quota quotidien par IP. - Les en-têtes d'identité servent uniquement à l'attribution et n'accordent jamais d'accès. ## URL de base Définissez BASE_URL sur l'origine du déploiement. Le produit hébergé utilise https://xmemo.dev ; le document OpenAPI validé déclare également http://localhost:8000 pour le développement local et https://api.memory-os.example.com comme serveur d'exemple. Les appels au plan de données REST utilisent les chemins /v1. ```bash BASE_URL="${BASE_URL:-https://xmemo.dev}" curl -sS "$BASE_URL/v1/recall?query=connection%20check&limit=1" \ -H "X-API-Key: $XMEMO_KEY" ``` ## En-tête d'authentification REST La plupart des requêtes REST transmettent l'en-tête de clé API. Les requêtes sans identifiant valide sont rejetées avant toute lecture ou écriture de mémoire ; POST /v1/agents/temporary-register est l'exception d'enregistrement temporaire documentée. Les identifiants présentés non valides sont rejetés. ```http X-API-Key: ``` ## Authentification MCP Les clients OAuth n'ont besoin que de l'URL du serveur hébergé. Les clients dynamiques non vérifiés doivent demander explicitement les portées de mémoire et de connaissances ; les clients vérifiés conservent la valeur par défaut existante lorsque la portée est omise. L'autorisation ne fournit que les portées approuvées. Les clients directs et sans interface graphique lisent plutôt le jeton depuis l'environnement. ```json { "servers": { "XMemo": { "type": "http", "url": "https://xmemo.dev/mcp" } } } ``` ## Périmètres (scopes) Le serveur évalue indépendamment les périmètres de l'identifiant et l'espace de mémoire demandé. Utilisez memory:read pour recall, search, context, list et les lectures de projets ; utilisez memory:write pour les écritures et mutations. Les opérations de connaissances exigent strictement knowledge:read et rejettent les jetons memory:read avec une erreur 403. Les jetons directs avancés peuvent utiliser des capacités plus restreintes telles que memory:update, memory:delete, memory:restore, memory:redact ou memory:hard_delete. Les alias REST hérités read:memories et write:memories restent des valeurs de compatibilité ; un périmètre n'élargit jamais l'autorisation du propriétaire, de l'équipe ou de l'espace de jeton. - Lecture : memory:read. - Écriture : memory:write ; les opérations de mutation peuvent nécessiter une capacité plus restreinte lorsque le profil de jeton la prend en charge. - Connaissances : knowledge:read ; strictement requis pour la recherche et le listing de connaissances (les jetons memory:read renvoient 403). - Accès projet/équipe : le propriétaire du jeton ou l'équipe liée ainsi que le rôle actif doivent également autoriser le scope/team_id demandé. - Les en-têtes d'attribution et les champs source identifient l'appelant ; ce ne sont pas des périmètres et ils n'accordent aucun accès. ## Schéma d'erreur Les chemins OpenAPI déclarent HTTPValidationError pour la validation de requête (422) et laissent la plupart des autres schémas de réponse non typés. L'erreur REST par défaut reste un objet JSON avec une valeur detail. Les échecs d'autorisation reconnus peuvent également être demandés sous forme d'application/problem+json conforme à la RFC 9457 ; utilisez le champ code pour le traitement automatisé plutôt que de comparer du texte brut. ```json { "detail": "invalid_token" } { "type": "urn:xmemo:problem:invalid_token", "title": "Invalid access token", "status": 401, "code": "invalid_token", "detail": "The presented access token is missing, expired, revoked, or otherwise invalid." } ``` ## Limites de débit OpenAPI ne publie pas de quotas de limite de débit. L'environnement d'exécution utilise une fenêtre fixe de 60 secondes lorsqu'il est activé (activé par défaut hors développement/local/test) : la catégorie de plan de données est de 600 requêtes par minute, les écritures de mémoire utilisent une politique de point de terminaison de 180 par minute, et les lectures memory search/recall/context utilisent une politique de point de terminaison de 300 par minute. Les opérateurs peuvent remplacer ces valeurs avec les variables d'environnement MEMORY_OS_RATE_LIMIT_* ; ne codez pas de quota en dur dans un client. - Réponse 429 : { detail: Rate limit exceeded, category, policy, limit, window_seconds, retry_after_seconds }. - En-têtes 429 : Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset et X-RateLimit-Policy. - Les réponses réussies exposent également les en-têtes X-RateLimit-* limit, remaining, reset et policy lorsque le limiteur est activé.