Authentification

Vue d'ensemble

Toutes les API AWDPay sont protégées par des tokens bearer à courte durée de vie. Les marchands s'authentifient en échangeant leur apiKey et secretKey émises depuis la console contre un token d'accès, puis attachent ce token à chaque appel API jusqu'à son expiration.

Cycle de vie des identifiants

1. Générer les clés – Dans le tableau de bord AWDPay, créez une paire de clés API pour Sandbox ou Production. Stockez la secretKey dans un coffre-fort (AWS Secrets Manager, HashiCorp Vault, etc.).
2. Approbation de conformité – Téléchargez les documents KYB/KYC. Les identifiants de production restent désactivés jusqu'à ce que l'équipe de risque AWDPay valide votre profil.
3. Échange côté serveur – Depuis un backend de confiance uniquement, appelez le point de terminaison de token avec apiKey + secretKey.
4. Attacher les tokens – Ajoutez l'en-tête Authorization: Bearer <token> à chaque requête Collections, Disbursement, Transfers ou d'abonnement webhook.
5. Renouveler – Les tokens expirent rapidement (par défaut 15 minutes). Rafraîchissez-les de manière proactive avant l'expiration ou réessayez avec un nouveau token lorsque vous recevez 401 invalid_token.

Point de terminaison du token

Méthode	Chemin	Charge d'authentification
POST	/api/auth/token	{ "apiKey": string, "secretKey": string }

• URL de base Sandbox : https://sandbox.awdpay.com
• URL de base Production : https://api.awdpay.com (ou le nom d'hôte régional communiqué par AWDPay)

Exemple de requête :

curl -X POST "$API_BASE_URL/api/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "merchant_api_key",
    "secretKey": "merchant_secret_key"
  }'

Réponse en cas de succès

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "issuedAt": "2025-11-20T09:02:14Z"
}

• expiresIn est exprimé en secondes ; AWDPay émet actuellement des tokens de 15 minutes.
• Les tokens sont des JWT opaques—traitez-les comme des secrets et ne les exposez jamais dans des applications mobiles ou des journaux côté client.

Utilisation du token

Attachez le token bearer à chaque requête API jusqu'à son expiration. L'exemple ci-dessous montre comment lister les passerelles de paiement activées pour Collections (vous pouvez remplacer par n'importe quel autre point de terminaison AWDPay) :

# Exemple : lister les passerelles de paiement disponibles pour le marchand
curl -X GET "$API_BASE_URL/api/gateways?flow=collections" \
  -H "Authorization: Bearer $AWDPAY_TOKEN"

// Exemple d'aide qui s'authentifie, puis liste les passerelles
const API_BASE_URL = process.env.AWDPAY_API_BASE_URL ?? 'https://sandbox.awdpay.com';

async function fetchGateways(flow = 'collections') {
  const tokenResponse = await fetch(`${API_BASE_URL}/api/auth/token`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ apiKey: process.env.AWDPAY_API_KEY, secretKey: process.env.AWDPAY_SECRET })
  });
  const { token } = await tokenResponse.json();

  const response = await fetch(`${API_BASE_URL}/api/gateways?flow=${flow}`, {
    headers: {
      Authorization: `Bearer ${token}`
    }
  });
  return response.json();
}

Cycle de vie du token & stratégie de nouvelle tentative

• Rafraîchissement proactif – Mettez en cache le token en mémoire/Redis et rafraîchissez-le 60 secondes avant expiresIn.
• Nouvelle tentative gracieuse – Si un appel API retourne 401 ou 403 avec invalid_token, demandez un nouveau token une fois et rejouez la requête originale.
• Rotation des clés – Effectuez une rotation de secretKey au moins tous les 90 jours. AWDPay permet des clés qui se chevauchent afin que vous puissiez émettre une nouvelle clé, déployer, puis révoquer l'ancienne clé sans temps d'arrêt.
• Concurrence – Utilisez des clés d'idempotence sur les opérations d'écriture afin que les nouvelles tentatives causées par les rafraîchissements de tokens restent sûres.

Bonnes pratiques de sécurité

• N'intégrez pas apiKey ou secretKey dans le code front-end ou les binaires mobiles.
• Restreignez le trafic sortant afin que seule votre couche API puisse atteindre les points de terminaison de token AWDPay.
• Activez TLS 1.2+ et l'épinglage de certificat lorsque c'est possible ; rejetez les réponses si la chaîne de certificats change de manière inattendue.
• Enregistrez les événements d'émission de tokens avec des ID de requête pour l'audit, mais n'enregistrez jamais les tokens bruts ou les secrets.
• Révoquez immédiatement les clés compromises via le tableau de bord AWDPay et purgez les tokens mis en cache.