API publique héritée - Living Security Platform

Ce guide porte sur les intégrations /api/v1 existantes qui échangent une clé d’accès d’API contre un jeton porteur. Leurs identifiants et leur format de requête 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 et la page Authentification. La nouvelle API /v1 utilise des clés d’API de compte de service ou des jetons d’accès OAuth.

Avant de commencer

Vous avez besoin de ce qui suit :

Un accès à Living Security qui permet la gestion des clés d’accès d’API
Une clé d’accès d’API créée sous 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’ID d’émetteur de l’API 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 le code de navigateur, les applications mobiles, le contrôle de version, les variables d’environnement côté client, les billets ni les journaux partagés.

La boîte de dialogue Access Keys affiche le secret à usage unique, mais elle n’affiche pas l’ID d’émetteur de l’API. Si Living Security ne vous a pas fourni l’ID d’émetteur avec vos identifiants d’API publique, demandez-le au soutien de Living Security. L’ID d’émetteur n’est ni l’ID de la clé d’accès ni l’ID 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
É.-U.	`https://api.us-east-1.livingsecurity.ai/api/v1`
UE	`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 des personnes de l’organisation et récupérer l’appartenance d’une personne
Clés d’accès d’API	Créer, lister, renouveler et révoquer des clés d’accès d’API

Utilisez Developers → Public API Reference pour obtenir la liste complète des opérations, des paramètres, des requêtes, des réponses et des schémas. Si une opération ne s’y trouve pas, elle ne fait pas actuellement partie de l’API publique.

Authentification

L’accès à l’API publique se déroule en deux étapes :

Échangez la clé d’accès secrète et l’ID d’émetteur de l’API contre un jeton porteur de courte durée et un ID d’organisation.
Envoyez le jeton porteur et l’ID d’organisation avec chaque requête d’API.

Les en-têtes de requête requis sont les suivants :

Authorization: Bearer <access-token>
x-organization-id: <organization-id>

L’en-tête d’organisation doit correspondre à l’organisation renvoyée par l’échange de la clé d’accès. Une clé n’autorise pas l’accès à un ID d’organisation arbitraire.

SDK TypeScript

Installez la version majeure actuelle :

npm install @livingsecurity/sdk@^1

Ensuite, échangez la clé et configurez le SDK :

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 de l’UE pour une organisation de l’UE. L’échange par 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 porteur et l’ID d’organisation avec chaque requête :

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 porteurs 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 porteur 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 à laquelle elles appartiennent.
Choisissez les portées les moins privilégiées proposées par le formulaire de clé d’accès.
Conservez immédiatement le secret à usage unique; il est impossible de le récupérer après la création ou le renouvellement.
Renouvelez une clé dans 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 offert à 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 est défini par défaut à 50 et accepte une valeur de 1 à 100.
cursor permet de poursuivre à partir d’une réponse précédente.
offset ignore un nombre d’enregistrements et est défini par défaut à 0.
includeTotal=true demande un décompte filtré exact; 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 en trier vous-même les résultats partiels.

Erreurs

Les erreurs JSON documentées suivent la forme générale suivante :

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

message peut être une chaîne ou un tableau de messages de validation.

État	Signification	Réponse
`400`	Paramètres ou corps de requête non valides	Corrigez les erreurs de validation indiquées
`401`	Le jeton porteur est manquant, non valide ou expiré	Échangez de nouveau la clé d’accès et réessayez une fois
`403`	L’identifiant n’a pas l’autorisation ou l’accès à l’organisation	Vérifiez les portées de la clé et le contexte de l’organisation
`404`	La ressource n’existe pas dans l’organisation autorisée	Vérifiez l’ID de la ressource et l’organisation
`408`	La requête a expiré	Réessayez avec un délai d’attente exponentiel borné
`429`	Limite de débit atteinte	Attendez au moins aussi longtemps que `Retry-After`, s’il est présent
`5xx`	Panne temporaire du service	Réessayez les lectures sûres avec un délai d’attente exponentiel borné

Le contrat organisé ne publie actuellement ni limite de débit numérique universelle ni garantie d’un en-tête de réponse contenant l’ID de requête pour chaque opération. Notez l’heure UTC, la méthode, le chemin, l’état et le corps de réponse épuré lorsque vous faites une demande de soutien. 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ésuétude

La V1 évolue par ajouts par défaut. Les clients doivent ignorer les champs de réponse inconnus. Un changement majeur exige un parcours de migration documenté; les opérations désuètes demeurent dans la référence avec leur motif, leur remplacement lorsqu’il existe et leur date de retrait pendant la période de migration. Fixez le SDK à une version majeure compatible et consultez ses notes de version avant de le mettre à niveau. Considérez la référence de l’API publique générée, et non les clients d’application internes, 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 des clients, partenaires et automatisation externe	Ressources stables et versionnées
MCP	Interactions avec des outils d’IA soumises à des autorisations	Contrats d’outils et sorties structurées compactes
Application Web	Flux de travail humains dans le produit Living Security	Contrats propres à l’application pouvant évoluer avec l’interface

Consultez Intégration MCP pour connecter un outil d’IA à Living Security.

Obtenir de l’aide

Communiquez avec le soutien de Living Security en fournissant les renseignements suivants :

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
L’état HTTP et le corps de l’erreur épuré

N’incluez jamais de secrets de clés d’accès, de jetons porteurs ni de données privées de clients.

Voir aussi

Clés d'accès d'API

Créez, renouvelez et révoquez des identifiants d’API.

Intégration MCP

Connectez les outils d’IA pris en charge par l’entremise du Model Context Protocol.

API publique

Référence de l'API publique

​Avant de commencer

​Hôtes régionaux

​Ressources héritées

​Authentification

​SDK TypeScript

​Requête REST directe

​Cycle de vie des clés d’accès

​Pagination

​Erreurs

​Compatibilité et désuétude

​API publique, MCP et application Web

​Obtenir de l’aide

​Voir aussi

Clés d'accès d'API

Intégration MCP

Avant de commencer

Hôtes régionaux

Ressources héritées

Authentification

SDK TypeScript

Requête REST directe

Cycle de vie des clés d’accès

Pagination

Erreurs

Compatibilité et désuétude

API publique, MCP et application Web

Obtenir de l’aide

Voir aussi