> ## Documentation Index > Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt > Use this file to discover all available pages before exploring further. # API publique héritée > Maintenez les intégrations /api/v1 existantes qui échangent une clé d'accès API contre un jeton d'accès (bearer token). Ce guide concerne les intégrations `/api/v1` existantes qui échangent une clé d'accès API contre un jeton d'accès (bearer token). Leurs identifiants et le format de leurs requêtes diffèrent de ceux de l'API publique `/v1`. Pour une nouvelle intégration, commencez par le [guide de démarrage rapide de l'API](/fr/developers/v1/quickstart) et la page [Authentification](/fr/developers/v1/authentication). La nouvelle API `/v1` utilise des clés API de compte de service ou des jetons d'accès OAuth. ## Avant de commencer Vous avez besoin des éléments suivants : * Un accès à Living Security autorisant la gestion des clés d'accès API * Une clé d'accès API créée dans **Paramètres → Access Keys** * Le secret de la clé d'accès, affiché une seule fois lors de la création de l'identifiant * L'identifiant d'émetteur de l'API (API issuer ID) fourni par Living Security avec vos identifiants d'API publique * L'URL de base régionale de l'organisation que vous intégrez * Un environnement d'exécution côté serveur et un gestionnaire de secrets Les secrets des clés d'accès ne doivent pas être placés dans du code de navigateur, des applications mobiles, un système de gestion de versions, des variables d'environnement côté client, des tickets ou des journaux partagés. La boîte de dialogue Access Keys affiche le secret à usage unique, mais pas l'identifiant d'émetteur de l'API. Si Living Security ne vous a pas fourni cet identifiant avec vos identifiants d'API publique, demandez-le au [support de Living Security](mailto:support@livingsecurity.com). L'identifiant d'émetteur n'est ni l'identifiant de la clé d'accès ni l'identifiant de l'organisation. ## Hôtes régionaux Le contrat hérité utilise les hôtes de production régionaux `/api/v1` suivants : | Région | URL de base | | - | - | | US | `https://api.us-east-1.livingsecurity.ai/api/v1` | | EU | `https://api.eu-west-1.livingsecurity.ai/api/v1` | Utilisez la région attribuée à l'organisation Living Security. Ne changez pas de région pour contourner une erreur d'autorisation ou de disponibilité. ## Ressources héritées | Ressource | Opérations prises en charge | | - | - | | **Personnes** | Rechercher les personnes de l'organisation et récupérer l'appartenance d'une personne | | **Clés d'accès API** | Créer, lister, renouveler et révoquer des clés d'accès API | Consultez **Developers → Public API Reference** pour la liste complète des opérations, paramètres, requêtes, réponses et schémas. Si une opération n'y figure pas, elle ne fait pas actuellement partie de l'API publique. ## Authentification L'accès à l'API publique se déroule en deux étapes : 1. Échangez la clé d'accès secrète et l'identifiant d'émetteur de l'API contre un jeton d'accès de courte durée et un identifiant d'organisation. 2. Envoyez le jeton d'accès et l'identifiant d'organisation avec chaque requête API. Les en-têtes de requête requis sont les suivants : ```http theme={null} Authorization: Bearer x-organization-id: ``` L'en-tête d'organisation doit contenir l'organisation renvoyée par l'échange de la clé d'accès. Une clé n'autorise pas l'accès à un identifiant d'organisation arbitraire. ### SDK TypeScript Installez la version majeure actuelle : ```bash theme={null} npm install @livingsecurity/sdk@^1 ``` Échangez ensuite la clé et configurez le SDK : ```typescript theme={null} import { configure, exchangeAccessKey } from "@livingsecurity/sdk"; const accessKeySecret = process.env.LS_API_ACCESS_KEY_SECRET; const apiIssuerId = process.env.LS_API_ISSUER_ID; if (!accessKeySecret || !apiIssuerId) { throw new Error("LS_API_ACCESS_KEY_SECRET and LS_API_ISSUER_ID are required"); } const { accessToken, organizationId } = await exchangeAccessKey( accessKeySecret, apiIssuerId, ); configure({ baseUrl: "https://api.us-east-1.livingsecurity.ai/api/v1", accessToken, organizationId, }); ``` Utilisez l'URL de base EU pour une organisation EU. L'échange via le SDK est destiné aux environnements d'exécution Node.js côté serveur. ### Requête REST directe Si vous effectuez l'échange en dehors du SDK, envoyez le jeton d'accès et l'identifiant d'organisation avec chaque requête : ```bash theme={null} curl --request GET \ "https://api.us-east-1.livingsecurity.ai/api/v1/people/search?limit=1" \ --header "Authorization: Bearer $LIVING_SECURITY_BEARER_TOKEN" \ --header "x-organization-id: $LIVING_SECURITY_ORG_ID" \ --header "Accept: application/json" ``` Les jetons d'accès sont de courte durée. Échangez de nouveau la clé d'accès pour obtenir un nouveau jeton plutôt que de conserver un jeton d'accès comme identifiant permanent. ## Cycle de vie des clés d'accès * Nommez les clés d'après l'intégration ou l'automatisation qui en est propriétaire. * Choisissez les portées (scopes) les plus restrictives proposées par le formulaire de clé d'accès. * Enregistrez immédiatement le secret à usage unique : il ne peut plus être récupéré après la création ou le renouvellement. * Renouvelez une clé via **Paramètres → Access Keys** et déployez la clé de remplacement avant de révoquer l'ancien identifiant. * Révoquez les clés qui ne sont plus utilisées ou dont le secret a pu être exposé. * Utilisez des clés de compte de service pour les intégrations non humaines lorsque ce type de clé est disponible pour votre organisation. ## Pagination La recherche de personnes prend en charge les paramètres `limit`, `cursor`, `offset` et `includeTotal`. Privilégiez le curseur renvoyé par la réponse précédente pour un parcours séquentiel. * `limit` vaut 50 par défaut et accepte des valeurs de 1 à 100. * `cursor` permet de poursuivre à partir d'une réponse précédente. * `offset` ignore un certain nombre d'enregistrements et vaut 0 par défaut. * `includeTotal=true` demande un décompte exact après filtrage ; omettez-le lorsque le décompte n'est pas nécessaire. Lisez l'objet `pagination` renvoyé par le point de terminaison. Ne calculez pas la page suivante à partir du nombre de lignes reçues et ne combinez pas des requêtes paginées indépendamment pour trier vous-même les résultats partiels. ## Erreurs Les erreurs JSON documentées ont la forme générale suivante : ```json theme={null} { "statusCode": 400, "message": "Validation failed", "error": "Bad Request" } ``` `message` peut être une chaîne de caractères ou un tableau de messages de validation. | Statut | Signification | Réponse | | - | - | - | | `400` | Paramètres ou corps de requête non valides | Corrigez les erreurs de validation indiquées | | `401` | Le jeton d'accès est manquant, non valide ou expiré | Échangez de nouveau la clé d'accès et réessayez une seule fois | | `403` | L'identifiant ne dispose pas des autorisations ou de l'accès à l'organisation | Vérifiez les portées de la clé et le contexte d'organisation | | `404` | La ressource n'existe pas dans l'organisation autorisée | Vérifiez l'identifiant de la ressource et l'organisation | | `408` | Délai d'attente de la requête dépassé | Réessayez avec un intervalle exponentiel borné (backoff) | | `429` | Limite de débit atteinte | Attendez au moins la durée indiquée par `Retry-After`, lorsqu'il est présent | | `5xx` | Défaillance temporaire du service | Réessayez les lectures sûres avec un intervalle exponentiel borné (backoff) | Le contrat validé ne publie actuellement ni limite de débit numérique universelle, ni en-tête de réponse contenant un identifiant de requête garanti pour chaque opération. Lorsque vous contactez le support, indiquez l'heure UTC, la méthode, le chemin, le statut et le corps de réponse expurgé des données sensibles. Ne réessayez pas automatiquement les opérations de création, de renouvellement, de révocation ou de suppression, sauf si l'opération documente explicitement son idempotence. Vérifiez l'état actuel de la ressource après une défaillance réseau ambiguë. ## Compatibilité et dépréciation La version V1 évolue par défaut de manière additive. Les clients doivent ignorer les champs de réponse inconnus. Toute modification incompatible nécessite un chemin de migration documenté ; les opérations obsolètes restent dans la référence avec leur motif, leur remplacement lorsqu'il existe et leur date de retrait pendant la période de migration. Figez le SDK sur une version majeure compatible et consultez ses notes de version avant toute mise à niveau. Considérez la référence de l'API publique générée, et non les clients d'applications propriétaires, comme la source de référence des schémas. ## API publique, MCP et application web | Surface | Utilisation | Modèle de compatibilité | | - | - | - | | **API publique** | Systèmes clients, partenaires et automatisation externe | Ressources stables et versionnées | | **MCP** | Interactions avec des outils d'IA soumises à autorisations | Contrats d'outils et sorties structurées compactes | | **Application web** | Workflows humains dans le produit Living Security | Contrats propres à l'application, susceptibles d'évoluer avec l'interface | Consultez [Intégration MCP](/fr/integrations/mcp) pour connecter un outil d'IA à Living Security. ## Obtenir de l'aide Contactez le [support de Living Security](mailto:support@livingsecurity.com) en précisant : * L'organisation et la région * Le nom et la version du SDK, le cas échéant * L'horodatage UTC, la méthode et le chemin * Le statut HTTP et le corps de l'erreur expurgé des données sensibles N'incluez jamais de secrets de clés d'accès, de jetons d'accès ni de données clients privées. ## Voir aussi Créez, renouvelez et révoquez des identifiants d'API. Connectez les outils d'IA pris en charge via le Model Context Protocol. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.