Documentation Authentication
Authentication
La clé
- Elle commence par
hl_emploi_live_et compte 63 caractères. Ce préfixe lisible permet aux outils de détection de secrets (GitHub, GitGuardian) de la repérer si elle est oubliée dans un dépôt. - Elle va dans l'en-tête de chaque appel :
Authorization: Bearer hl_emploi_live_VOTRECLE. Jamais dans une adresse, un dépôt de code ou une page web publique. - Elle appartient à une page et à cette API seule : elle ne lit ni ne touche les offres d'une autre page, et une clé de l'API Formation reçoit 403 ici (comme celle-ci sur l'API Formation).
- Elle ne marche que tant que la page a la formule Grands comptes : sans elle, chaque appel répond 403.
- Elle ne fait que ce que ses droits permettent :
offres:lecture,offres:ecriture(publier permet aussi de lire). - Facultatif, à sa création : une durée de vie (30 jours, 90 jours, 1 an) et une liste
d'adresses IP autorisées (par exemple
203.0.113.0/24) ; un appel venu d'ailleurs répond 403. - Une page peut avoir jusqu'à dix clés actives sur l'API Emploi : une par logiciel, pour pouvoir en couper une sans toucher les autres. Révoquer une clé la coupe aussitôt.
- Remplacer une clé (rotation) en crée une nouvelle aux mêmes réglages, durée de vie comprise ; l'ancienne marche encore 7 jours, le temps de la changer dans votre logiciel, sans coupure. Si la clé a fuité, choisissez le remplacement d'urgence : l'ancienne est coupée tout de suite, avec ses jetons OAuth.
- Une clé d'essai (
hl_emploi_test_) a sa propre limite d'appels, plus basse que celle d'une vraie clé (GET /moila donne).
Le bac à sable
Une clé d'essai commence par hl_emploi_test_. Elle donne exactement les mêmes réponses,
validations et erreurs qu'une vraie clé, mais ses offres vivent à part : elles ne sont jamais
publiées ni vues des membres. Vous pouvez les créer, les lister, les modifier, les archiver et les
supprimer comme de vraies offres ; elles sont effacées 7 jours après leur dernière modification.
Chaque réponse porte "bac_a_sable": true et l'en-tête Heyalink-Bac-A-Sable: oui. Vos
webhooks de test sont prévenus aussi, avec "bac_a_sable": true dans donnees. Branchez votre
logiciel avec elle, puis passez à une clé hl_emploi_live_.
Le journal de test (GET /journal avec la clé d'essai, ou l'écran API Emploi) garde chaque
appel avec sa requête et sa réponse complètes, secrets masqués.
La validation à blanc
Avec une vraie clé, ajoutez ?dry_run=1 à n'importe quelle écriture (ou l'en-tête
Heyalink-Simulation: 1) : tout est vérifié (clé, droits, champs, référence) et la réponse est
celle d'une vraie écriture, avec "simulation": true. Rien n'est écrit.
curl -X PUT "https://heyalink.com/api/emploi/v1/offres/CC-2026-014?dry_run=1" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE" \
-H "Content-Type: application/json" \
-d '{
"titre": "Chef de chantier gros œuvre",
"description": "<p>Deux équipes.</p>",
"lieu": "Toulouse"
}'
Essayer sans rien installer
- « Essayer » dans cette documentation, connecté à Heyalink : chaque exemple part avec un jeton du bac à sable de votre page.
- Données d'exemple valides telles quelles : offres.json.
- Collections prêtes à importer, tirées de la spécification OpenAPI de l'API Emploi :
Postman,
Bruno. Mettez votre clé d'essai
dans la variable
cle. - Tester ma source (écran API Emploi) : ce que Heyalink importerait de votre page carrières, de votre logiciel ou de votre flux, champ par champ, avec les erreurs, sans rien publier.
OAuth 2.0
Si votre logiciel préfère OAuth, échangez la clé contre un jeton d'une heure (octroi
« client credentials », RFC 6749) : client_id est l'identifiant client de la clé (hlc_…,
affiché sur l'écran API Emploi), client_secret la clé elle-même. scope restreint les droits
du jeton (facultatif), pris parmi offres:lecture et offres:ecriture.
curl -X POST "https://heyalink.com/api/emploi/v1/oauth/token" \
-u "hlc_VOTREIDENTIFIANT:hl_emploi_live_VOTRECLE" \
-d grant_type=client_credentials \
-d scope="offres:ecriture"
{
"access_token": "hl_at_…",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "offres:ecriture"
}
Le jeton s'emploie ensuite comme une clé : Authorization: Bearer hl_at_…. Il ne vaut que pour
l'API Emploi, et tombe avec la clé (révocation, expiration).
Les anciennes clés
- Les clés de l'ancienne API Recruteur Premium (
hlk_…, adresse/api/recruteur/v1) marchent toujours, jusqu'à leur remplacement depuis l'écran API Emploi : « Remplacer » donne une cléhl_emploi_live_; l'ancienne marche encore 7 jours (ou s'arrête tout de suite en urgence). - Les clés créées avant le 21 octobre 2026 (
hle_…,hl_live_…,hl_test_…) marchent aussi jusqu'à leur remplacement. Leur API se déduit de leurs droits : avecoffres:…, elles ouvrent l'API Emploi. Leur remplacement donne une clé de l'API Emploi seule. - L'ancienne adresse commune
/api/entreprises/v1reste servie pour elles ; le cloisonnement des deux API y vaut aussi. Passez àhttps://heyalink.com/api/emploi/v1à votre rythme.
Prouver votre domaine
Une publication pour de bon (et sa validation à blanc) demande que votre page ait prouvé qu'elle possède le domaine de son site. Un SIRET vérifié dit que l'entreprise existe, pas que c'est bien elle qui publie : la preuve de domaine protège vos candidats contre une page qui usurperait votre nom. Le bac à sable, lui, reste ouvert sans preuve. Les domaines prouvés sont ceux de la page : ils valent pour l'API Emploi comme pour l'API Formation.
- Déclarez le domaine :
POST /domainesavec{"domaine": "votre-site.fr"}, ou sur l'écran API Emploi. La réponse donne un jeton propre au domaine. - Posez-le sur votre site, au choix : la balise
<meta name="heyalink-verification" content="JETON">dans la page d'accueil, ou un fichierhttps://votre-site.fr/.well-known/heyalink.txtqui contient le jeton. - Vérifiez :
POST /domaines/votre-site.fr/verification.domaine.prouvepasse àtrue.
Le domaine prouvé vaut aussi pour ses sous-domaines (carrieres.votre-site.fr). Le lien de
candidature de vos offres (lien_candidature) doit mener à un domaine prouvé de votre page :
sinon l'offre est refusée en 422, sur le champ. Une page carrières ou un flux déjà prouvés comme
source valent preuve de leur domaine. La preuve est revue chaque semaine : retirée de votre site,
elle ne compte plus. Il n'y a pas d'autre voie : pas de validation à la main. GET /domaines
liste vos domaines, DELETE /domaines/votre-site.fr en retire un.
This section is written in French; the OpenAPI 3.1 specification describes every field.