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

?api_key= est également accepté, mais les en-têtes évitent d’inscrire le secret dans les URL et l’historique. Stockez les clés côté serveur et remplacez toute clé exposée.

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:write`	Créer/modifier par POST et retirer des offres.
`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.
`405`	Employer la méthode HTTP prise en charge.
`409`	Une requête idempotente peut être en cours ; patienter brièvement.
`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.

Pour réessayer une création d’offre, réutilisez le même Idempotency-Key. La référence prévoit une répétition de la réponse réussie pendant 24 heures. Utilisez une nouvelle valeur pour une autre opération. Voir API des offres.