API publique héritée

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 et la page Authentification. 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. 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 :

É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.
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 :

Authorization: Bearer <access-token>
x-organization-id: <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 :

npm install @livingsecurity/sdk@^1

Échangez ensuite 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 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 :

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 :

{
  "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 pour connecter un outil d’IA à Living Security.

Obtenir de l’aide

Contactez le support de Living Security 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.

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

Erreurs

Compatibilité et dépréciation

API publique, MCP et application web

Obtenir de l’aide

Voir aussi

Clés d'accès API

Intégration MCP

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épréciation

​API publique, MCP et application web

​Obtenir de l’aide

​Voir aussi

Clés d'accès 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épréciation

API publique, MCP et application web

Obtenir de l’aide

Voir aussi