Authentification

L'API SOAMTAR utilise des clés API porteuses (bearer) sur HTTPS uniquement. Toute requête nécessite un header Authorization.

Types de clés

SOAMTAR fournit deux types de clés pour chaque environnement (test et live) :

Type	Préfixe	Usage	Sécurité
Clé publique	pk_...	Intégration côté client (SOAMTAR.js, SDK mobiles).	Sûre pour une exposition publique.
Clé secrète	sk_...	Requêtes API côté serveur (SDK PHP, Python…).	SENSIBLE. Ne jamais l'exposer.

Format d'authentification

Toute requête envoyée par votre serveur à l'API SOAMTAR doit porter votre clé secrète dans le header Authorization.

Authorization: Bearer sk_(test|live)_<votre-cle-secrete>

Attention

N'utilisez jamais votre clé publique (pk_...) pour l'authentification bearer depuis votre serveur. Elle est réservée au JavaScript exécuté dans le navigateur de votre client.

Environnements (modes)

Préfixe	Usage
sk_test_	Sandbox. Aucune transaction réelle. Les réponses contiennent livemode: false.
sk_live_	Production. Transactions et reversements réels. livemode: true.

Ne mélangez jamais les deux : les objets de test et de production sont isolés — une clé de test ne voit pas les objets live, et inversement.

Scopes

Chaque clé porte un sous-ensemble de capacités. Créez des clés à privilèges minimaux :

Scope	Permission
can_initiate_payment	POST/payments, POST/subscriptions, POST/payments/{id}/splits
can_read_transactions	GET/payments, GET/payments/{id}, GET/subscriptions, GET/disputes
can_refund	POST/refunds
can_payout	POST/payouts

Une requête sans le scope requis renvoie 403 scope_insufficient.

Rotation

Dashboard → Développeurs → Clés API → Rotate.

• L'ancienne clé reste valide 24 h après la rotation pour permettre la migration.
• Toute clé peut être révoquée immédiatement.
• SOAMTAR journalise chaque utilisation : clé, adresse IP, scope demandé, horodatage.

Liste blanche d'IP (optionnel)

Pour une clé live, vous pouvez restreindre les adresses IP autorisées :

Dashboard → Clés API → Edit → Allowed IPs : 41.x.x.x, 41.y.y.y/24

Toute requête depuis une IP non listée renvoie 401 invalid_api_key.

Signature des requêtes (optionnelle)

En plus de la clé Bearer, vous pouvez signer chaque requête mutante (POST, PUT, PATCH, DELETE) avec votre clé secrète. Cela prouve que la requête a été construite par un détenteur du secret et limite les rejeux à une fenêtre de 5 minutes. Les requêtes GET ne sont jamais vérifiées.

En-tête	Valeur
Soamtar-Timestamp	Heure Unix courante, en secondes
Soamtar-Signature	v1= + hex(HMAC-SHA256(clé_secrète, "<timestamp>.<MÉTHODE>.<chemin>"))

• <MÉTHODE> est en majuscules (POST).
• <chemin> est le chemin de la requête sans la barre oblique initiale ni la query string, par ex. v1/payments, v1/refunds.
• Le timestamp doit être à ±300 s de l'horloge SOAMTAR, sinon l'API répond 400 invalid_timestamp. Un en-tête qui ne commence pas par v1= reçoit 400 invalid_signature.

const crypto = require('crypto');
const ts = Math.floor(Date.now() / 1000).toString();
const sig = crypto.createHmac('sha256', process.env.SOAMTAR_SECRET_KEY)
  .update(`${ts}.POST.v1/payments`).digest('hex');

headers['Soamtar-Timestamp'] = ts;
headers['Soamtar-Signature'] = `v1=${sig}`;

La signature est un durcissement optionnel : les requêtes sans les deux en-têtes sont acceptées et, aujourd'hui, une signature incorrecte est journalisée plutôt que refusée. L'application stricte peut être activée sur toute la plateforme ; une signature fausse renvoie alors 401 invalid_signature. Vérifiez donc que vos signatures sont valides avant de vous appuyer dessus.

Chaque SDK serveur peut signer pour vous :

SDK	Option
Node.js	require('@soamtar/sdk')(key, { signRequests: true })
PHP	new SoamtarClient($key, ['sign_requests' => true])
Python	SoamtarClient(key, sign_requests=True)
Ruby	Soamtar::Client.new(key, sign_requests: true)
Go	soamtar.NewClient(key, soamtar.WithSignRequests(true))
Java / .NET	paramètre signRequests du constructeur

Voir la page de chaque SDK pour le constructeur exact.

Erreurs d'authentification

Code	Cause
missing_credentials	Header Authorization absent
invalid_api_key	Clé inconnue, révoquée ou expirée, ou IP hors liste blanche
scope_insufficient	Clé valide mais sans le scope requis pour cette route

Sécurité

• Jamais en clair côté client : n'exposez jamais une clé secrète live dans une page web, une application mobile ou un dépôt git public.
• Stockage chiffré : conservez vos clés dans un gestionnaire de secrets (Vault, AWS Secrets Manager, Doppler).
• Rotation régulière : au moins tous les 6 mois.
• Hash uniquement : SOAMTAR ne stocke qu'un hash de votre clé. Si vous la perdez, faites une rotation.