Authentification, réponses et erreurs API

Envoyer la clé dans un en-tête

Utilisez l’un des deux en-têtes :

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Envoyez un seul en-tête d’authentification. Les routes privées des offres, espaces et connexions refusent les identifiants dans l’URL, même avec un en-tête valide. Conservez les clés côté serveur.

Permissions et types

Permission	Utilisation
`read`	Lecture des ressources couvertes par l’API.
`write`	Lecture et écriture ; inclut la lecture.
`jobs:read`	Lire les offres.
`jobs:draft`, `jobs:publish`, `jobs:edit`, `jobs:lifecycle`	Enregistrer un brouillon, publier ou republier, modifier ou retirer, respectivement. Les anciennes autorisations `jobs:write` conservent leurs opérations.
`spaces:read`	Lire les espaces.
`cities:read`	Rechercher les villes ; `read` couvre aussi cette fonction.
`events:read`	Lire les événements.

Les clés cwk_rstr_ sont en lecture seule ; cwk_live_ permet les écritures configurées. Le préfixe seul ne donne aucun droit : les permissions et restrictions d’espace restent applicables. Une permission d’écriture d’offres ne donne pas toutes les permissions de lecture.

Format des réponses

Une réponse réussie contient success, status et data. Les offres utilisent data.jobs ; les villes et espaces renvoient des tableaux.

{
  "success": false,
  "status": 422,
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": ["Job title is required"]
  }
}

error.details peut être un tableau ou un objet, notamment pour les permissions et limitations. Vérifiez le type avant de parcourir les détails. Traitez aussi les erreurs réseau et les réponses non JSON.

Corriger les erreurs

Statut HTTP	Action
`400`	Vérifier le JSON et le format de requête.
`401`	Vérifier la clé, l’expiration, la révocation et les restrictions IP.
`403`	Vérifier les permissions et l’espace de l’offre.
`404`	Vérifier l’endpoint et l’identifiant. Les chemins v1 supprimés peuvent renvoyer ce statut ; utilisez l’API v2.
`405`	Employer la méthode HTTP prise en charge.
`409`	Consultez le code d’erreur. Pour `job_exists`, lisez l’offre existante. Si la révision a changé, relisez l’offre avant de confirmer.
`410`	`api_version_retired` : migrer la requête vers l’API v2. Répéter la requête v1 ou renouveler sa clé ne rétablit pas l’accès. Voir le retrait de v1 et la migration.
`422`	Corriger les champs de `error.details`.
`429`	Attendre `error.details.retry_after_seconds`, puis réessayer avec un délai croissant et aléatoire.
`500`	Réessayer prudemment ; transmettre le contexte sans secret à l’équipe.

Les écritures d’offres sont limitées par clé. La référence indique une valeur de repli de 120 écritures/minute, mais la limite configurée de la clé est prioritaire. Utilisez les valeurs de la réponse.

Réutilisez le même Idempotency-Key et le même corps pour répéter une requête identique. Le reçu ordinaire reste en cache jusqu’à 24 heures et peut être indisponible. Vérifiez l’offre après une réponse incertaine. Voir API des offres.