Authentification

L’API Royal Finance utilise deux mécanismes selon le contexte :

• Clés API (rs_test_… / rs_live_…) pour les serveurs partenaires.
• JWT (access + refresh) pour les apps utilisateur ou marchand qui agissent au nom d’un compte humain.

1. Clés API serveur

Envoyée dans le header Authorization: Bearer <clé> sur tous les appels serveur-à-serveur. Ne diffusez jamais une clé rs_live_ côté client.

curl https://api.royalstack.com/api/v1/wallets/me \
  -H "Authorization: Bearer rs_live_••••"

2. JWT utilisateur

Pour les apps mobiles / web qui authentifient un humain, on génère un access token (15 min) et un refresh token (30 jours).

Connexion client

curl -X POST https://api.royalstack.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+22670111213", "password": "••••••••" }'

Réponse :

{
  "access_token":  "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "expires_in":    900,
  "user": { "id": "usr_3K2x9Vp", "phone": "+22670111213", "kyc": "verified" }
}

3. 2FA

Lorsque le compte a la 2FA activée, /auth/login renvoie un challenge :

{ "challenge": "ch_8x2L", "method": "sms", "expires_in": 300 }

Validez avec :

curl -X POST https://api.royalstack.com/api/v1/auth/2fa/verify \
  -d '{ "challenge": "ch_8x2L", "code": "418256" }'

Permissions

Les clés API supportent des scopes. Le scope manquant renvoie un 403 :

| Scope | Endpoints | |------------------|------------------------------------------| | payments:read | GET /payments, GET /payments/{id} | | payments:write | POST /payments, POST /refunds | | wallets:read | GET /wallets, GET /wallets/{id} | | wallets:write | POST /wallets/transfer |