API publique

L’API REST publique d’Elba fournit un accès en lecture seule aux données de sécurité de l’organisation à des fins de reporting et d’intégration.

URL de base régionales

Utilisez l’endpoint de la région dans laquelle votre espace Elba est hébergé :

N’envoyez pas la clé API d’un espace européen à l’endpoint américain, ni celle d’un espace américain à l’endpoint européen.

Créer une clé API

1. Dans l’espace d’administration Elba, ouvrez Paramètres → Général.
2. Recherchez Clés API et créez une clé avec un nom descriptif.
3. Copiez la valeur générée et stockez-la dans un gestionnaire de secrets approuvé.
4. Supprimez les clés qui ne sont plus utilisées.

Traitez une clé API comme un mot de passe. Ne la publiez jamais dans un dépôt, ne la collez pas dans des journaux visibles par les clients et ne l’exposez pas dans du code exécuté par le navigateur.

Authentifier une requête

Envoyez la clé sous forme de jeton Bearer :

curl --request GET \
  --header "Authorization: Bearer $ELBA_API_KEY" \
  "https://api.eu.elba.security/v1/users?limit=100&offset=0"

Remplacez le nom d’hôte par l’endpoint américain lorsque votre espace est hébergé aux États-Unis.

Ressources disponibles

L’API actuelle comprend des endpoints en lecture seule pour :

• les utilisateurs et les indicateurs du classement ;
• la progression des formations ;
• les résultats des simulations de phishing ;
• les problèmes de protection des données ;
• les comptes, l’inventaire et les problèmes liés aux applications tierces.

La plupart des endpoints de liste acceptent limit et offset. Utilisez la pagination et demandez uniquement les données dont vous avez besoin.

Inventaire canonique des applications (v2)

La version 2 expose les applications tierces comme un inventaire unifié. Elle combine les comptes vérifiés provenant des intégrations d’identité et OAuth, l’activité e-mail qui constitue un indice corroborant, ainsi que l’usage depuis le navigateur, le contexte des comptes IA et les extensions installées qui restent des observations inférées. Une observation navigateur ne devient jamais un compte.

La version 2 est disponible pour tous les espaces de travail. La version 1 reste disponible et inchangée.

La réponse existante de GET /v1/tpa/inventory ne change pas et continue de contenir uniquement les comptes associés issus des connecteurs.

Lister les applications

curl --request GET \
  --header "Authorization: Bearer $ELBA_API_KEY" \
  "https://api.eu.elba.security/v2/tpa/inventory?limit=100&offset=0"

GET /v2/tpa/inventory renvoie un élément par application canonique ou privée à l’espace de travail. Chaque élément contient :

• l’identité canonique et la classification du produit ;
• la politique de l’organisation, son domaine navigateur applicable lorsqu’il existe, la criticité et le responsable ;
• la posture de l’application et l’exposition des accès dans deux évaluations distinctes ;
• les nombres d’utilisateurs et d’indices par type ;
• les sources de détection ainsi que les dates de première et dernière observation ;
• le contexte agrégé des comptes IA professionnel, personnel, mixte, déconnecté ou inconnu.

La réponse par défaut contient les applications, suites et extensions de navigateur autonomes actives ou à vérifier ; identity.inventory_state permet de les distinguer. Les détections ambiguës, sites web, appareils, plateformes et composants système restent dans le processus de classification d’Elba et ne sont pas renvoyés comme applications avant leur validation.

La posture du catalogue est nullable : application_posture vaut null pour une application provisoire privée. Pour une application observée uniquement dans le navigateur, access_exposure.assessment vaut no_verified_access_evidence.

identity.domain décrit l’identité applicative validée et peut provenir d’une validation portant sur un hôte exact. policy.enforceable_domain est volontairement plus strict : il ne contient qu’un domaine enregistrable sûr et validé que Browser Security peut appliquer, et vaut null lorsqu’un tel domaine n’existe pas. Une politique refusée avec une valeur null reste visible mais n’est pas appliquée au trafic navigateur.

Les noms de champs et les valeurs d’énumérations de l’API restent en anglais. Les groupes principaux sont identity, policy, application_posture, access_exposure, evidence_counts, detection_sources, freshness et ai_account_context.

[
  {
    "application_handle": "notion",
    "identity": {
      "type": "catalog",
      "name": "Notion",
      "entity_kind": "application",
      "inventory_state": "active",
      "url": "https://www.notion.so",
      "logo_url": "https://cdn.example/notion.svg",
      "domain": "notion.so",
      "publisher": "Notion Labs",
      "description": "Connected workspace",
      "parent_application_handle": null,
      "observed_surface": null
    },
    "policy": {
      "status": "allowed",
      "enforceable_domain": "notion.so",
      "criticality_level": 2,
      "owner": null
    },
    "application_posture": {
      "assessment": "assessed",
      "trust_score": 86,
      "is_verified": true,
      "last_reviewed_at": "2026-07-10T09:00:00Z",
      "cves": [],
      "breaches": []
    },
    "access_exposure": {
      "assessment": "available",
      "verified_users": 12,
      "high_risk_permissions": 1
    },
    "evidence_counts": {
      "total_users": 15,
      "current_users": 14,
      "stale_browser_users": 1,
      "verified_users": 12,
      "idp_accounts": 8,
      "oauth_grants": 4,
      "email_activity": 3,
      "browser_usage": 10,
      "browser_ai_account_context": 0,
      "browser_extension_installations": 0
    },
    "detection_sources": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "Google Workspace",
        "logo_url": null,
        "evidence_types": ["oauth_grant"],
        "strengths": ["verified"],
        "freshness": {
          "first_seen_at": "2026-01-12T10:00:00Z",
          "last_seen_at": "2026-07-18T08:00:00Z",
          "state": "fresh"
        }
      }
    ],
    "freshness": {
      "first_seen_at": "2026-01-12T10:00:00Z",
      "last_seen_at": "2026-07-18T08:00:00Z",
      "state": "fresh"
    },
    "ai_account_context": {
      "work": 0,
      "personal": 0,
      "mixed": 0,
      "signed_out": 0,
      "unknown": 0
    }
  }
]

Lister les utilisateurs et leurs indices pour une application

Encodez applicationHandle pour une utilisation dans une URL lors de la construction du chemin.

curl --request GET \
  --header "Authorization: Bearer $ELBA_API_KEY" \
  "https://api.eu.elba.security/v2/tpa/inventory/notion/users?limit=100&offset=0"

GET /v2/tpa/inventory/:applicationHandle/users pagine les personnes ou comptes de connecteur non rattachés, et non les lignes d’indices individuelles. Chaque indice conserve sa source et reçoit le niveau verified, corroborated ou inferred. Seul un indice issu d’un connecteur peut avoir can_remediate à true.

[
  {
    "identity": {
      "type": "elba_user",
      "id": "00000000-0000-0000-0000-000000000000",
      "email": "[email protected]",
      "display_name": "Alex Martin",
      "profile_picture_url": null
    },
    "freshness": {
      "first_seen_at": "2026-05-01T08:00:00Z",
      "last_seen_at": "2026-07-18T08:00:00Z",
      "state": "fresh"
    },
    "evidence": [
      {
        "type": "browser_extension_installation",
        "strength": "inferred",
        "source": {
          "id": "00000000-0000-0000-0000-000000000001",
          "name": "Chrome Browser Security",
          "logo_url": null
        },
        "first_seen_at": "2026-05-01T08:00:00Z",
        "last_seen_at": "2026-07-18T08:00:00Z",
        "freshness": "fresh",
        "authentication": null,
        "ai_account_context": null,
        "installation_state": "installed",
        "extension_installation": {
          "state": "installed",
          "enabled": true,
          "install_type": "admin",
          "version": "4.5.6",
          "permission_summary": {
            "permission_names": ["storage", "tabs"],
            "unknown_permission_count": 1,
            "host_permission_count": 2,
            "host_permission_scope": "specific_sites"
          }
        },
        "can_remediate": false
      }
    ]
  }
]

Une identité elba_user contient l’identifiant, l’adresse e-mail, le nom affiché et l’image de profil du membre dans l’annuaire Elba. Si ce membre est supprimé ou n’est plus inscrit, son identifiant Elba stable reste disponible tandis que email, display_name et profile_picture_url valent null ; les indices navigateur ne sont alors plus courants, tandis que les indices issus des connecteurs conservent leur propre état et peuvent maintenir le sujet à l’état fresh. Une identité external_account ne peut provenir que d’un connecteur. Elle contient un identifiant opaque stable account:<sha256>, des champs email et display_name facultatifs, ainsi que la source du connecteur. Son identifiant n’est jamais dérivé d’une activité navigateur ni de données de compte exposées. Chaque ligne d’indice contient notamment :

• type, strength et source ;
• first_seen_at, last_seen_at et freshness ;
• la méthode d’authentification et le marqueur is_inferred lorsqu’ils sont disponibles ;
• l’état d’installation, la facette extension_installation, le contexte du compte IA et can_remediate.

Un indice navigateur ne fournit jamais l’identifiant d’un compte externe. L’adresse e-mail d’un elba_user vient de l’annuaire des membres, pas du contenu du navigateur. Un indice IA expose uniquement son contexte : il ne révèle jamais l’adresse e-mail détectée, le domaine du compte, l’URL de la page, le prompt ou son contenu.

extension_installation n’est renseigné que pour un indice browser_extension_installation. Son résumé de permissions préserve la confidentialité : permission_names contient uniquement des noms reconnus de permissions API du navigateur qui ne donnent pas accès à un hôte ; les valeurs non reconnues sont représentées uniquement par unknown_permission_count ; et l’accès aux sites est réduit à un compteur et au périmètre none, specific_sites, all_sites ou unknown. Les motifs d’hôtes bruts, noms d’hôtes, domaines et URL complètes ne sont jamais renvoyés. permission_summary vaut null pour les observations signalées par d’anciennes versions de l’extension. Cette facette observée dans le navigateur reste inférée et non remédiable : elle ne constitue ni un compte d’application ni une évaluation de permissions OAuth.

Une observation navigateur reste fresh pendant 30 jours après last_seen_at, puis demeure disponible avec l’état stale. Cette règle d’expiration ne s’applique pas aux indices issus des connecteurs. La fraîcheur vaut unknown pour une application sans horodatage d’indice exploitable.

Erreurs courantes

Pour consulter le schéma complet et la structure des réponses, utilisez la référence OpenAPI fournie avec votre espace Elba ou contactez le support Elba.