Authentification

L'API Diamond Careers utilise une authentification par jeton Bearer JWT, émis par le plugin JWT Authentication for WP REST API installé sur la plateforme. Vous récupérez un jeton via une seule requête, puis vous le passez en en-tête HTTP sur chaque appel.

Les jetons API sont délivrés à tout compte WordPress de la plateforme, mais les permissions appliquées dépendent du rôle. Pour une intégration externe (ATS, SIRH), un compte technique avec rôle etablissement ou groupe est créé par notre équipe : voir la procédure dans Vue d'ensemble.

Vue d'ensemble

┌──────────┐     POST /wp-json/jwt-auth/v1/token       ┌─────────────────┐
│  Client  │ ───────────────────────────────────────▶  │  Diamond API    │
│  ATS/SIRH│   { username, password }                  │                 │
└──────────┘                                           └─────────────────┘
      ▲                                                         │
      │            { token, user_email, user_display_name }     │
      └─────────────────────────────────────────────────────────┘

┌──────────┐  Authorization: Bearer <token>            ┌─────────────────┐
│  Client  │ ─────────────────────────────────────▶    │  Diamond API    │
└──────────┘                                           └─────────────────┘

Obtenir un jeton

curl -X POST "https://diamondcareers.fr/wp-json/jwt-auth/v1/token" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "integration@votre-etablissement.com",
    "password": "VotreMotDePasseTechnique"
  }'

Le champ username accepte indifféremment l'email ou l'identifiant WordPress du compte.

Réponse :

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user_email": "integration@votre-etablissement.com",
  "user_nicename": "integration-etablissement",
  "user_display_name": "Intégration ATS"
}

Le jeton a une durée de validité encodée dans son claim exp (timestamp Unix). La durée par défaut du plugin JWT est de 7 jours. Stockez-le côté serveur, jamais dans le navigateur de l'utilisateur final.

Récupérer le profil

curl "https://api.diamondcareers.fr/diamond/v1/auth/me" \
  -H "Authorization: Bearer <votre_token>"

Réponse type :

{
  "id": 42,
  "email": "integration@votre-etablissement.com",
  "display_name": "Intégration ATS",
  "role": "etablissement",
  "linked": {
    "type": "maison",
    "id": 87,
    "member_role": "owner"
  }
}

Utiliser le jeton

Sur chaque requête vers /diamond/v1/*, ajoutez l'en-tête Authorization préfixé de Bearer :

curl "https://api.diamondcareers.fr/diamond/v1/offres" \
  -H "Authorization: Bearer <votre_token>"

Si le jeton est valide et le périmètre cohérent, vous recevez 200 OK avec la ressource. Sinon 401 Unauthorized (jeton invalide/expiré) ou 403 Forbidden (hors périmètre).

Vérifier la validité

Le moyen le plus simple : appeler GET /diamond/v1/auth/me.

curl "https://api.diamondcareers.fr/diamond/v1/auth/me" \
  -H "Authorization: Bearer <votre_token>"

200 OK avec un objet utilisateur → jeton valide. 401 → jeton expiré ou invalide, régénérez-en un.

Le plugin JWT propose aussi un endpoint dédié POST /wp-json/jwt-auth/v1/token/validate qui répond 200 ou 403.

Cycle de vie

Renouvellement à expiration. Utilisez le jeton jusqu'à recevoir une 401, puis appelez à nouveau /wp-json/jwt-auth/v1/token pour un nouveau. Simple, mais peut introduire un délai d'erreur en pleine action.

Renouvellement préventif. Lisez le claim exp du jeton et renouvelez-le avant expiration. Plus robuste pour les intégrations critiques.

// Extraire la date d'expiration du jeton
function getTokenExpiration(token) {
  const payloadBase64 = token.split('.')[1];
  const payload = JSON.parse(Buffer.from(payloadBase64, 'base64').toString());
  return new Date(payload.exp * 1000);
}

Cookie + nonce (SPA même domaine, lecture seule)

Si vous consommez l'API depuis un client navigateur hébergé sur diamondcareers.fr (cas de la SPA Next interne), une alternative au JWT existe : authentification par cookie WordPress + nonce REST.

# 1. Récupérer le nonce (cookie WP existant requis)
curl "https://diamondcareers.fr/wp-json/diamond/v1/auth/bootstrap" \
  --cookie "wordpress_logged_in_xxx=..."

# Réponse :
# { "logged_in": true, "user": {...}, "nonce": "abc123..." }

# 2. Utiliser le nonce sur les requêtes suivantes
curl "https://diamondcareers.fr/wp-json/diamond/v1/auth/me" \
  --cookie "wordpress_logged_in_xxx=..." \
  -H "X-WP-Nonce: abc123..."

Ce flux n'est pas adapté aux intégrations externes (cookies cross-domain bloqués). Préférez le JWT pour tout client serveur.

Périmètre du jeton

Un jeton est lié au compte qui l'a généré. Concrètement :

• Compte établissement : accès limité à la maison rattachée. Vous ne voyez que vos propres offres, candidatures, articles, médias. Une tentative d'accès à une autre maison renvoie 403 Forbidden.
• Compte groupe : accès aux maisons rattachées au groupe. Vous voyez en lecture l'ensemble des offres et candidatures de ces maisons, et accédez aux endpoints /groupes/{id}/* agrégés.

Au sein de l'établissement, la granularité est portée par le rôle membre :

• owner — gestion complète : offres, candidatures, articles, équipe.
• editor — gestion des offres, candidatures et articles. Pas de gestion d'équipe.
• viewer — lecture seule.

Les actions interdites par le rôle renvoient 403 Forbidden.

Bonnes pratiques de sécurité

Stockez les identifiants côté serveur uniquement. Jamais dans du code côté client (navigateur, mobile). Utilisez des variables d'environnement ou un coffre-fort secrets.

HTTPS obligatoire. Toutes les communications passent en HTTPS.

Renouvelez les mots de passe régulièrement. Le compte technique doit avoir un mot de passe long et unique, renouvelé au moins une fois par an.

Limitez les permissions au strict nécessaire. Demandez le rôle adapté à votre besoin (souvent editor suffit pour un ATS qui pousse des offres et lit des candidatures, owner n'est utile que si vous gérez aussi l'équipe).

Erreurs courantes