Documentation › L’API REST

Connecter une autre application : l'API REST

Votre ERP, votre SIRH ou vos propres scripts peuvent lister vos process publiés, lancer des instances de process avec leurs valeurs et suivre leur avancement, sans que personne n'ouvre SerenForce. Ils s'identifient avec une clé d'API de votre organisation.

⏱ 5 minutes📍 Menu Settings › API keys✅ Prérequis : un process publié

L'API REST est incluse dans l'offre Business. Avec une offre inférieure, la page affiche seulement Not included in your plan et l'API refuse les appels. Seuls les administrateurs de l'organisation gèrent ses clés d'API.

1. Créer une clé d'API

  1. Ouvrez le menu Settings, puis, dans la rubrique Administration, API keys.
  2. Cliquez sur New API key, donnez un Name qui dit ce qui l'utilise (par exemple « SIRH ») et choisissez une Expiry : Never, dans 30 jours, 90 jours ou un an.
  3. Cliquez sur Create the key. La clé s'affiche une seule fois : copiez-la avec Copy the key et rangez-la en lieu sûr (le coffre de secrets de votre autre application), puis cliquez sur I have copied the key.

Ensuite, la liste ne montre plus que le début de la clé (pn_1a2b3c4d…), son état (Active, Expired, Revoked), sa date d'expiration et sa dernière utilisation. SerenForce ne garde qu'une empreinte de la clé : si vous la perdez, créez-en une nouvelle et révoquez l'ancienne.

2. Ce qu'une clé peut faire

Une clé agit dans cette organisation, au nom de l'administrateur qui l'a créée, avec des droits limités :

Elle ne termine aucune tâche (c'est la personne à qui la tâche est assignée qui la fait), ne modifie aucun process et n'administre rien. Elle ne voit jamais une autre organisation. Elle cesse de fonctionner quand elle est révoquée, quand elle expire, ou quand son créateur n'administre plus l'organisation.

3. Appeler l'API

La page API keys affiche l'Address of the API de votre organisation, de la forme https://…/api/votre-organisation/public/v1, avec un bouton pour la copier. Chaque appel envoie la clé dans l'en-tête Authorization: Bearer votre-clé (ou X-Api-Key: votre-clé). Exemples avec curl :

# Les process publiés
curl -H "Authorization: Bearer pn_votre-clé" https://…/api/votre-organisation/public/v1/processes

# Lancer une instance de process
curl -X POST -H "Authorization: Bearer pn_votre-clé" -H "Content-Type: application/json" \
  -d '{"processId":"…","name":"Intégration de Marie","variables":[{"name":"Ordinateur","value":"MacBook"}],"participants":[{"name":"Manager","email":"paul@exemple.com"}]}' \
  https://…/api/votre-organisation/public/v1/process-instances

# Suivre l'instance de process et ses tâches
curl -H "Authorization: Bearer pn_votre-clé" https://…/api/votre-organisation/public/v1/process-instances/…/tasks

4. Les réponses à connaître

Chaque lancement fait par une clé apparaît dans le journal d'audit au nom de son créateur.

5. Révoquer une clé

Cliquez sur Revoke à côté de la clé, puis confirmez. Les applications qui l'utilisent sont refusées tout de suite ; la clé reste dans la liste (Revoked) pour garder une trace. Pour leur rendre l'accès, créez une nouvelle clé.