API du journal d’activité

NordPass Enterprise propose désormais une intégration de l’API du registre d’activité pour vous aider à gérer l’accès des membres et à surveiller les activités au sein de votre organisation. Vous trouverez ci-dessous des instructions sur la manière dont les Propriétaires et les Administrateurs peuvent consulter les journaux d’activité via l’API.

Remarque : avant de poursuivre, assurez-vous que les autorisations de compte sont configurées en suivant le guide de gestion des jetons NordPass.

Configuration de l’API

Les URL de l’API Registre d’activité sont spécifiques au centre de données : votre organisation doit utiliser l’URL correspondant au centre de données où se trouve votre compte.

• UE : https://api-activities.eu.nordpass.com/activities/query 
• États-Unis : https://api-activities.us.nordpass.com/activities/query 

En-tête de la demande

Lorsque vous effectuez une requête POST vers l’API Registre d’activité, veillez à inclure les deux en-têtes ci-dessous :

• Autorisation – La requête POST vers une API de journaux d’activité doit être autorisée à l’aide du jeton généré sur le panneau d’administration Business. 
• Content-Type : lors du lancement d’une requête POST, il est essentiel d’inclure un en-tête Content-Type pour indiquer explicitement le type de média des données transmises dans le corps de la requête.
  Pour l’API Registre d’activité, vous devez définir le type de contenu sur application/json, car la requête est transmise au format JSON.

Exemple :

Autorisation : GENERATED_ACTIVE_TOKEN
			Content-Type : application/json

Filtrage & pagination

• Cette API permet de filtrer par timestamp_from et timestamp_to. Si le filtre facultatif n’est pas fourni, les informations sont renvoyées pour les 7 derniers jours complets. La période spécifiée pour le filtrage ne doit pas dépasser un maximum de 90 jours.

• Le filtre user_uuids est facultatif. S’il n’est pas fourni, les informations renvoyées concerneront tous les utilisateurs, sur la base d’autres critères de filtrage. Ce filtre accepte un tableau de valeurs de type chaîne, ce qui permet d’inclure jusqu’à 500 identifiants UUID d’utilisateur dans une seule requête de filtre :

  1. Connectez-vous au panneau d’administration en tant que propriétaire ou administrateur.

  2. Ouvrez le mode développeur.

  3. Accédez à la section Membres dans le menu de gauche.

  4. En mode Développeur, ouvrez l’onglet Réseaux et recherchez v1/ecp/users.

  5. L’en-tête doit afficher une requête GET.

  6. Récupérez les UUID de tous les utilisateurs actifs dans l’onglet Réponse.
     
     Remarque : les mêmes étapes doivent être suivies pour obtenir les UUID des utilisateurs suspendus et supprimés.
      

• Vous pouvez également utiliser la fonction de recherche par item_id. Cela vous permet de trouver plus rapidement des journaux d’activité spécifiques, car tout ce dont vous avez besoin est l’UUID de 36 caractères de l’élément.

• En outre, vous pouvez gérer le nombre d’enregistrements renvoyés en utilisant l’option de filtrage per_page , qui permet d’obtenir entre 1 et 100 enregistrements par requête. Si l’option per_page n’est pas spécifiée, la valeur par défaut sera de 30 enregistrements par page.

• L’option de filtrage Page permet de demander des résultats de page spécifiques. Le numéro de page doit être au moins 1 et ne peut pas dépasser le nombre total de pages disponibles. Si l’option page n’est pas spécifiée, l’API renverra par défaut la première page.

Exemple :

{
			  "timestamp_from": TIMESTAMP_FILTER_FROM,
			  "timestamp_to": TIMESTAMP_FILTER_TO,
			  "user_uuids": ["USER_UUID"],
			  "item_id": "ITEM_UUID",
			  "per_page": 30,
			  "page": 1
			}

Récupération complète des données

Pour conserver un enregistrement complet, sans lacunes, nous recommandons notre approche de rétention des données, selon laquelle les événements générés pendant les interruptions sont conservés et synchronisés dès que le service est rétabli. Votre implémentation est responsable de la récupération complète des données en maintenant un curseur basé sur l’horodatage. NordPass ne rejoue pas les événements manqués et ne les transmet pas par push. La partie intégrante est responsable de la mise en œuvre de ce modèle pour garantir une piste d’audit sans lacune.

Pour garantir une récupération complète des données, procédez comme suit :

1. À partir de la requête API reçue, prenez l’activité la plus récente/la dernière reçue (chaque activité a son propre horodatage indiquant le moment où elle s’est produite) et vérifiez son horodatage.
2. Lors de la création d’une nouvelle requête API, utilisez ce filtre :
   {
   "timestamp_from": TIMESTAMP_OF_LAST_RECEIVED_ACTIVITY + 1
   }
   
   Remarque : le filtre "timestamp_to": CURRENT_TIMESTAMP peut être facultativement utilisé pour limiter le nombre de résultats.
   
    
3. Cela vous permet de toujours recevoir les activités les plus récentes, même pendant de brèves interruptions de service. Une fois le service rétabli, le filtre reste en place afin que vous receviez les informations les plus récentes du journal d’activité, sans aucune lacune.

Limites de débit

L’API est limitée à 2 000 demandes toutes les 5 minutes par adresse IP.

Réponses

Vous trouverez une liste des actions effectuées par les membres de votre organisation dans la section types d’actions du guide du journal d’activité.

{
			    "data": [
			        {
			            "type": string,
			            "action": string,
			            "timestamp": integer,
			            "organization_uuid": string($uuid),
			            "user": {
			                "uuid": string($uuid),
			                "email": string($email)
			            },
			            "metadata": []
			        }
			    ],
			    "metadata": {
			        "total": integer, 
			        "per_page": integer, 
			        "current_page": integer, 
			        "total_pages": integer,
			    }
			}

Limitation

L’API peut renvoyer jusqu’à 10 000 enregistrements les plus récents du journal d’activité (par exemple, demander les journaux 9980-10050 ne renverra aucun résultat). Si les résultats du filtrage dépassent cette limite, seuls les 10 000 résultats les plus récents seront renvoyés.

Codes d’erreur