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. Seuls les droits que l’API sait faire sont proposés : Encaisser d’abord (créer et voir les paiements, cochés d’office), le reste sous Avancé : les liens de paiement, le catalogue, les clients, les factures, l’argent qui sort, et le suivi. Le « i » de chaque droit dit ce qu’il ouvre.

Une clé ne porte rien d’autre : un geste qui ne vit qu’à l’écran (l’équipe, les webhooks, les réglages) est refusé à sa création. Une clé plus ancienne qui en porterait encore les perd, sans effet sur ce qu’elle fait, à sa prochaine modification ou à son renouvellement.

Gérer les clients ouvre aussi le numéro d’un client en clair (POST /v1/customers/{id}/phone) : chaque lecture s’inscrit au journal d’audit de votre espace, au nom de la clé, et la réponse ne se garde nulle part.

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 droit Lancer sur le téléphone (Paiements · lancer) permet à la clé d’envoyer la demande sur le téléphone du payeur : c’est le 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

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 :

{
  "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.