API keys et API publique

OpenAleph propose une API publique, appelée API partenaire, afin que les systèmes de votre entreprise (généralement votre SIRH ou un outil d'intégration) puissent envoyer les données des membres à OpenAleph et les relire. L'accès est contrôlé par des API keys que les admins créent dans l'espace Company developer.

Avant de commencer

• Vous devez être Admin. Les admins à accès limité et les autres niveaux ne peuvent ni voir ni utiliser les API keys.
• Une API key appartient à votre entreprise, pas à une personne. Elle continue de fonctionner si l'admin qui l'a créée quitte l'entreprise.

Ouvrir l'espace Company developer

1. En bas du menu principal, cliquez sur l'icône de code (info-bulle API keys), à côté de Aide & Support.
2. La page Company developer s'ouvre en pleine page, sans le menu principal (« Here you can manage your developer settings, including API keys and event reporting functionalities. »). Elle comporte deux cartes :
   • Go to api keys : création et gestion de vos API keys pour accéder aux API d'OpenAleph ;
   • Go to ETL reports : liste des exécutions de synchronisation et de leurs statuts (voir Intégrations et synchronisation SIRH).

Créer une API key

1. Cliquez sur Go to api keys. La page Api keys liste les clés existantes avec leur Nom, leur ID public et leur date Créé le.
2. Cliquez sur Créer une API key.
3. Saisissez un Nom de l'API key (obligatoire), par exemple « Synchro SIRH - production », puis cliquez sur Enregistrer.
4. Le message de confirmation de création apparaît et le Secret de l'API key s'affiche. Copiez-le (icône de copie à côté du secret) et conservez-le en lieu sûr (gestionnaire de mots de passe ou coffre de secrets de votre intégration).
5. Cliquez sur Fait.

Révoquer une API key

1. Sur la page Api keys, cliquez sur l'icône corbeille de la ligne de la clé.
2. Confirmez Confirmer la suppression de la clé API : « La suppression de cette clé API révoquera immédiatement son accès. Toutes les intégrations ou scripts qui l'utilisent cesseront de fonctionner jusqu'à leur mise à jour. Continuer ? »
3. Cliquez sur Supprimer. « API key supprimée avec succès. » le confirme : la clé disparaît de la liste et cesse immédiatement de fonctionner. Quand il ne reste aucune clé, la page affiche « Vous n’avez généré aucune API key jusqu’à présent. »

Pour renouveler une clé sans interruption : créez une nouvelle clé, mettez à jour votre intégration, vérifiez qu'elle fonctionne, puis supprimez l'ancienne clé.

Utiliser l'API

Authentification

Envoyez la clé dans l'en-tête Authorization de chaque requête :

Authorization: Bearer VOTRE_API_KEY

Une clé absente ou invalide renvoie une erreur 401 avec l'indication « Pass your API key in the Authorization header as: Bearer YOUR_API_KEY ».

URL de base et versions

• Version actuelle : https://app.openaleph.io/partners/v2
• Ancienne version (création de membres uniquement) : https://app.openaleph.io/partners/v1

Ce que permet l'API

L'API partenaire couvre les données des membres et les listes qui décrivent votre organisation. Elle ne donne pas accès aux entretiens, formations, objectifs ou autres contenus des modules.

Règles principales :

• Les membres sont identifiés par leur company_uid (votre matricule). Champs obligatoires : company_uid, email, firstname, lastname, status, access_level.
• Chaque envoi de membre est une mise à jour complète : envoyez tous les champs obligatoires à chaque fois.
• Le manager se définit avec manager_company_uid. Les champs de profil personnalisés s'envoient dans extras, avec les identifiants fournis par /users_schema.
• Les admins à accès limité peuvent être envoyés avec leur périmètre (perimeter et exclusions), voir Admins à accès limité et périmètres.
• Envoyer status: inactive désactive le membre et enregistre une date de départ.
• Les endpoints groupés pour les intitulés de poste, options et unités acceptent jusqu'à 1 000 éléments par appel et peuvent être appelés à chaque fois avec vos listes complètes sans risque.
• La création et la mise à jour de membres acceptent un en-tête Idempotency-Key, afin qu'une requête relancée ne soit pas appliquée deux fois.

Documentation de référence de l'API

La documentation interactive complète (formats de requête et de réponse, exemples, codes d'erreur) est disponible sur https://app.openaleph.io/api-docs. Sélectionnez API V2 partners dans la liste.

Questions fréquentes

J'ai perdu le secret d'une clé.

Il ne peut pas être réaffiché. Créez une nouvelle clé, mettez à jour votre intégration, puis supprimez l'ancienne.

Je ne vois pas l'icône de code dans le menu.

Elle n'est affichée qu'aux admins.

J'ai envoyé un membre via l'API mais je ne vois pas la modification.

Les modifications sont appliquées lors de la prochaine synchronisation quotidienne. Consultez le rapport ETL de cette exécution dans Company developer › Go to ETL reports.

Puis-je utiliser l'API pour exporter les réponses aux entretiens ou les résultats de formation ?

Non. Utilisez les exports disponibles dans chaque module, voir Exports et rapports.