Démarrage rapide de l'API

Créez un compte de service et une clé API dans le Developer Hub, puis effectuez votre première requête. Ce guide de démarrage rapide utilise l’authentification par clé API; vous n’avez pas besoin d’un client OAuth. Consultez la section 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 Comptes de service et créez un compte. Donnez-lui un nom descriptif (par exemple reporting-pipeline) et accordez-lui les permissions que ses clés pourront utiliser; pour ce guide, organization:read suffit.Les permissions du compte constituent le plafond de chaque clé créée sous celui-ci : une clé ne peut jamais faire plus que ce que son compte de service autorise.

Créer une clé API

Ouvrez la page de détails du compte de service et créez une clé. Choisissez les permissions dont cette clé précise a besoin (un sous-ensemble de celles du compte) ainsi qu’une date d’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.

N’enregistrez jamais les secrets de clé API dans le contrôle de version et ne les intégrez pas dans du code côté client. Toute personne détenant le secret peut agir avec les permissions de la clé.

Choisir votre région

Appelez l’hôte régional /v1 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
É.-U.	`https://api.us-east-1.livingsecurity.ai/v1`
UE	`https://api.eu-west-1.livingsecurity.ai/v1`

Consultez la section Régions si vous ne savez pas quel hôte utiliser. Une clé valide envoyée à l’autre région échoue avec l’erreur 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 à partir de 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 du mot de passe ou dans celui du nom d’utilisateur de l’authentification HTTP Basic : les deux fonctionnent, de sorte que les clients qui exigent que les deux champs soient remplis (comme le connecteur Web de Power BI) peuvent saisir une valeur de remplacement 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 Journaux des requêtes 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 prennent en charge que le nom d’utilisateur 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 l’erreur invalid_request. L’hôte doit tout de même correspondre à la région de cette organisation. Consultez la section Régions.
Les permissions sont vérifiées pour chaque opération. Chaque opération /v1 exige une permission nommée (par exemple, GET /v1/organization exige organization:read). Une clé à laquelle il manque la permission reçoit une erreur 403 avec le code insufficient_permission.
Les clés expirent et peuvent être renouvelées sans interruption de service. Consultez la section Clés API pour la rotation avec une période de chevauchement.

Lecture des réponses d’erreur

Chaque erreur /v1 est de type application/problem+json (RFC 9457) et comporte 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
}

Basez votre logique de branchement sur code, jamais sur detail. Suivez doc_url pour connaître les étapes de résolution, et incluez request_id lorsque vous communiquez avec le soutien : il correspond à l’en-tête de réponse Request-Id et aux journaux des requêtes du Developer Hub. L’ensemble complet des codes figure dans la référence des erreurs.

Versions du contrat

Chaque réponse renvoie 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 pour la corrélation. Vous pouvez associer une requête à une version publiée du contrat au moyen d’une 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 prise en charge est dépassée) renvoie une erreur 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	Prochaine action
`401 unauthorized`	Vérifiez le secret, sa date d’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 limitée.
Délai d’attente réseau dépassé	Vérifiez la connectivité et relancez cette lecture dans les limites du budget de nouvelles tentatives de votre application.

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

Prochaines étapes

Régions

Choisissez l’hôte /v1 des É.-U. ou de l’UE 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 état HTTP et la façon de le résoudre.

Developer Hub

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

Centre des 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

Prochaines étapes

Régions

Pagination

Limites de débit

Référence des erreurs

Developer Hub

Centre des 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

​Prochaines étapes

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

Prochaines étapes