> ## Documentation Index
> Fetch the complete documentation index at: https://developers.0flaw.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Démarrage

> Provisionnez vos employés et recevez vos événements de sécurité en moins de trois minutes.

L'API 0flaw sert deux usages : **pousser vos employés** depuis votre SIRH ou votre annuaire,
et **recevoir les événements de sécurité** dans votre SIEM. Elle est conçue pour être branchée
une fois puis oubliée.

## 1. Créez une clé API

Dans le dashboard : **Réglages → Clés API**. Choisissez les permissions, puis copiez la clé
immédiatement.

<Warning>
  La clé n'est affichée **qu'une seule fois**. Elle est stockée hachée chez nous : nous ne pouvons
  pas vous la redonner. En cas de doute, révoquez-la et créez-en une nouvelle — la révocation est
  immédiate.
</Warning>

## 2. Vérifiez qu'elle fonctionne

`GET /api/v1/ping` ne demande aucune permission : c'est le premier appel à faire.

```bash theme={null}
curl https://api.0flaw.fr/api/v1/ping \
  -H "Authorization: Bearer 0flaw_live_votre_cle"
```

```json theme={null}
{
  "ok": true,
  "entreprise_id": "00000000-0000-0000-0000-000000000000",
  "scopes": ["write:employees"],
  "api_key_id": "7c1e…"
}
```

## 3. Synchronisez vos employés

Commencez **toujours** par une simulation : `dry_run` renvoie le rapport complet sans écrire
la moindre donnée.

```bash theme={null}
curl -X POST https://api.0flaw.fr/api/v1/employees/sync \
  -H "Authorization: Bearer 0flaw_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "employees": [
      { "external_id": "hr-4821", "email": "jane.doe@acme.com",
        "nom": "Doe", "prenom": "Jane", "secteur": "Finance" }
    ],
    "dry_run": true
  }'
```

Le rapport détaille, employé par employé, ce qui **serait** fait : `created`, `updated`,
`reactivated`, `skipped` ou `failed`. Une fois le résultat conforme à vos attentes, relancez
sans `dry_run`.

<Tip>
  Fournissez un `external_id` stable (l'identifiant de votre SIRH). C'est lui qui permet de suivre
  un employé **même si son adresse email change** — sans lui, un changement d'email est vu comme
  un départ suivi d'une arrivée.
</Tip>

## 4. Recevez les événements

Configurez un webhook pour être notifié en quelques secondes lorsqu'un employé clique sur un
lien de phishing ou saisit ses identifiants.

<Card title="Configurer les webhooks" icon="webhook" href="/webhooks">
  Format des livraisons, vérification de signature et politique de réessais.
</Card>

## Principes à connaître

<CardGroup cols={2}>
  <Card title="Une clé, une entreprise" icon="building">
    Une clé ne peut ni lire ni modifier les données d'une autre entreprise. L'identifiant
    d'entreprise n'est jamais un paramètre : il est déduit de la clé.
  </Card>

  <Card title="Opérations idempotentes" icon="rotate">
    Rejouer une synchronisation ne crée aucun doublon. Un même événement webhook n'est jamais
    livré deux fois.
  </Card>

  <Card title="Aucune suppression définitive" icon="archive">
    L'API désactive (archive) les employés : leur historique de campagnes et de formations est
    conservé.
  </Card>

  <Card title="Limite de débit" icon="gauge">
    600 requêtes par tranche de 15 minutes et par clé, avec des en-têtes `RateLimit-*` sur
    chaque réponse.
  </Card>
</CardGroup>