# Clés d’API

Une clé par usage : votre site, votre caisse, votre logiciel. Les clés secrètes restent sur vos serveurs.

## Une seule sorte de clé

Une clé (`sk_test_…`, `sk_live_…`) agit en votre nom. Elle vit sur votre serveur, dans un coffre à secrets — jamais dans une page web, jamais dans une application mobile, jamais dans un dépôt de code. Une page sans serveur n’en a pas besoin : le widget y ouvre un lien de paiement.

Chaque mode a ses clés. Une clé `sk_test_` parle au simulateur et ne déplace aucun argent ; une clé `sk_live_` déplace de l’argent réel.

## Créer une clé

Dans votre espace : **Développeurs › Clés API › Nouvelle clé**. Vous choisissez son nom, ce qu’elle a le droit de faire, et — si vous le voulez — les seules adresses IP d’où elle peut parler. Le code de votre application d’authentification confirme le geste.

**Le secret ne s’affiche qu’une fois.** Payiz n’en garde que l’empreinte : personne, pas même le support, ne peut le relire. Perdu ? Renouvelez la clé.

## Lancer sur le téléphone

Le geste **Paiements · lancer** permet à la clé d’envoyer la demande sur le téléphone du payeur : c’est le [paiement direct](https://docs.payiz.app/paiement-direct). Donnez-le à une clé qui ne quitte pas vos serveurs, et restreignez ses adresses. En réel, il ne se donne que si votre palier ouvre le direct : l’espace le grise, avec sa raison, tant que ce n’est pas le cas.

## S’authentifier

```bash
curl https://api.payiz.app/v1/account \
  -H "Authorization: Bearer sk_test_votre_cle"
```

Sans clé, ou avec une clé refusée, l’API répond 401 :

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Cette clé est refusée.",
    "request_id": "req_01j9x3t8m2k4c7vd9qhs"
  }
}
```

## Renouveler et révoquer

- **Renouveler** : une nouvelle clé prend la suite et l’ancienne reste valable **24 h**, le temps de la remplacer partout sans couper le service.
- **Révoquer** : la clé cesse de valoir tout de suite. Ce qui l’utilise encore recevra une erreur 401 — visible dans vos journaux.

## Bonnes habitudes

- Une clé par usage, pour révoquer sans tout casser.
- Les droits au plus juste : une caisse n’a pas besoin de retirer.
- Les adresses autorisées, si votre serveur a une IP fixe — toujours pour une clé qui lance.
- Le secret dans les variables d’environnement de votre hébergeur.