Démarrage rapide de l'API

Créez un compte de service et une clé d’API dans le Developer Hub, puis effectuez votre première requête. Ce démarrage rapide utilise l’authentification par clé d’API ; vous n’avez pas besoin d’un client OAuth. Consultez Authentification si votre intégration nécessite des jetons d’accès OAuth de courte durée.

Prérequis

Un accès administrateur au Tableau de bord de Living Security.
Le Developer Hub visible sous Paramètres → Intégrations & Developers → Developer Hub.

Créer les identifiants

Créer un compte de service

Dans le Developer Hub, ouvrez l’onglet Service accounts et créez un compte. Donnez-lui un nom descriptif (par exemple reporting-pipeline) et accordez-lui les autorisations que ses clés pourront utiliser — pour ce guide, organization:read suffit.Les autorisations du compte constituent le plafond pour chaque clé créée sous celui-ci : une clé ne peut jamais faire plus que ce que son compte de service permet.

Créer une clé d'API

Ouvrez la page de détail du compte de service et créez une clé. Choisissez les autorisations dont cette clé spécifique a besoin (un sous-ensemble de celles du compte) et une expiration — 30, 90 ou 365 jours, ou une période personnalisée. L’expiration est obligatoire.Le secret de la clé commence par lsk_live_ et n’est affiché qu’une seule fois. Copiez-le immédiatement dans un gestionnaire de secrets ; il ne pourra pas être récupéré ultérieurement.

Ne validez jamais de secrets de clé d’API dans un système de gestion de versions et ne les intégrez pas dans du code côté client. Toute personne qui détient le secret peut agir avec les autorisations de la clé.

Choisir votre région

Appelez l’hôte /v1 régional qui correspond à la résidence des données de l’organisation. Les clés ne s’authentifient que sur cet hôte.

Région	URL de base
US	`https://api.us-east-1.livingsecurity.ai/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/v1`

Consultez Régions si vous ne savez pas quel hôte utiliser. Une clé valide envoyée à l’autre région échoue avec unauthorized. Utilisez la liste déroulante des régions de l’exemple ci-dessous pour changer d’hôte.

Effectuer votre première requête

Chargez LIVING_SECURITY_API_KEY depuis votre gestionnaire de secrets dans l’environnement du processus qui effectue la requête. Les exemples ci-dessous le lisent sans intégrer de secret dans le code source. Pour Python, installez d’abord requests.Appelez l’API en indiquant le secret dans le champ de mot de passe ou dans le champ d’identifiant de l’authentification HTTP Basic — l’un ou l’autre fonctionne, de sorte que les clients qui exigent que les deux champs soient renseignés (comme le connecteur Web de Power BI) peuvent saisir une valeur fictive telle que apikey dans l’autre champ.

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}:" \
  -H "Living-Security-Version: 2026-07-01"

import os
import requests

BASE = "https://api.eu-west-1.livingsecurity.ai/v1"

response = requests.get(
    f"{BASE}/organization",
    auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
    headers={"Living-Security-Version": "2026-07-01"},
    timeout=(5, 30),
    allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 200:
    raise RuntimeError("Unexpected response; check your regional API URL")
print(response.json())

Une réponse réussie renvoie votre organisation :

Response

{
  "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
  "object": "organization",
  "name": "Example Corp",
  "region": "eu",
  "plan": "enterprise",
  "subscription_status": "active",
  "created_at": "2024-03-12T18:04:11.000Z"
}

Si vous obtenez cette réponse, vos identifiants fonctionnent. La requête apparaît également dans l’onglet Request logs du Developer Hub en quelques instants.

L’authentification Bearer avec le même secret (Authorization: Bearer lsk_live_...) fonctionne également. L’authentification Basic existe afin que les outils qui ne gèrent que l’identifiant et le mot de passe — comme le connecteur Web de Power BI — puissent se connecter.

Fonctionnement de l’authentification

L’identifiant détermine l’organisation. Les requêtes /v1 ne comportent aucun sélecteur de locataire : ni segment de chemin d’organisation, ni en-tête d’organisation. L’envoi d’un en-tête x-organization-id est rejeté avec invalid_request. L’hôte doit toujours correspondre à la région de cette organisation. Consultez Régions.
Les autorisations sont vérifiées pour chaque opération. Chaque opération /v1 requiert une autorisation nommée (par exemple, GET /v1/organization requiert organization:read). Une clé qui ne dispose pas de l’autorisation reçoit un 403 avec le code insufficient_permission.
Les clés expirent et peuvent être renouvelées sans interruption de service. Consultez Clés d’API pour effectuer une rotation avec une période de chevauchement.

Lecture des réponses d’erreur

Chaque erreur /v1 est au format application/problem+json (RFC 9457) avec un code machine stable. Par exemple, une requête dont l’identifiant est manquant ou inconnu renvoie :

401 Unauthorized

{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API credential was provided.",
  "code": "unauthorized",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "retryable": false
}

Appuyez-vous sur code, jamais sur detail. Suivez doc_url pour connaître les étapes de résolution, et indiquez request_id lorsque vous contactez le support — il correspond à l’en-tête de réponse Request-Id et aux journaux de requêtes du Developer Hub. L’ensemble complet des codes figure dans la référence des erreurs.

Versions du contrat

Chaque réponse reprend la version du contrat qui l’a servie dans l’en-tête Living-Security-Version, accompagnée d’un en-tête Request-Id destiné à la corrélation. Vous pouvez associer une requête à une version publiée du contrat par sa date :

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

La version est résolue dans l’ordre suivant : l’en-tête de la requête s’il est présent, sinon la version par défaut épinglée du compte de service, sinon la dernière version publiée. Demander une version qui n’est pas publiée (ou dont la date de fin de support est dépassée) renvoie un 400 avec le code unsupported_version. Les versions publiées et leurs modifications sont répertoriées dans le journal des modifications de l’API.

Dépanner votre première requête

Résultat	Action suivante
`401 unauthorized`	Vérifiez le secret, son expiration et la région de l’organisation. N’essayez pas d’autres hôtes avec un identifiant actif.
`403 insufficient_permission`	Accordez `organization:read` au compte de service et à sa clé.
`400 unsupported_version`	Choisissez une version publiée dans le journal des modifications.
`429 rate_limited`	Attendez `Retry-After` ; suivez l’exemple de nouvelle tentative bornée.
Délai d’attente réseau dépassé	Vérifiez la connectivité et relancez cette lecture dans la limite du budget de nouvelles tentatives de votre application.

Pour les autres erreurs, suivez doc_url de la réponse. Conservez Request-Id pour le support ; n’incluez jamais l’en-tête Authorization ni votre clé d’API dans un ticket.

Étapes suivantes

Régions

Choisissez l’hôte /v1 US ou EU pour l’organisation.

Pagination

Parcourez les listes avec page_token et l’enveloppe de liste.

Limites de débit

Comprenez les budgets de requêtes et gérez les réponses 429.

Référence des erreurs

Chaque code d’erreur, son statut HTTP et la manière de le résoudre.

Developer Hub

Gérez les comptes de service, les clés d’API et les journaux de requêtes.

Hub développeurs

API publique v1

Référence de l'API v1

Prérequis

Créer les identifiants

Fonctionnement de l’authentification

Lecture des réponses d’erreur

Versions du contrat

Dépanner votre première requête

Étapes suivantes

Régions

Pagination

Limites de débit

Référence des erreurs

Developer Hub

Hub développeurs

API publique v1

Référence de l'API v1

​Prérequis

​Créer les identifiants

​Fonctionnement de l’authentification

​Lecture des réponses d’erreur

​Versions du contrat

​Dépanner votre première requête

​Étapes suivantes

Régions

Pagination

Limites de débit

Référence des erreurs

Developer Hub

Prérequis

Créer les identifiants

Fonctionnement de l’authentification

Lecture des réponses d’erreur

Versions du contrat

Dépanner votre première requête

Étapes suivantes