# Authentification, réponses et erreurs API

Source: https://docs.coworkies.com/fr/api/authentication/

> Utilisez les en-têtes de clé, comprenez les permissions et traitez les erreurs de validation, d’accès et de limitation.

## Envoyer la clé dans un en-tête

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

```text
X-API-Key: YOUR_API_KEY
```

```text
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.

```json
{
  "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](https://docs.coworkies.com/fr/api/jobs/).