Auth et limites de l’API revendeur

Jetons Bearer, autorisations, liste d’IP autorisées, limite de débit, codes d’erreur, clés d’idempotence et pagination de l’API revendeur.

Jetons

Un jeton ressemble à rsk_ suivi de 40 caractères. Créez-le dans l’espace client (onglet revendeur, « API et paramètres ») ; la valeur n’est affichée qu’une fois, nous ne conservons qu’un hachage et les 4 derniers caractères. Vous pouvez avoir jusqu’à 10 jetons actifs et en révoquer n’importe lequel à tout moment. Un jeton peut recevoir une durée de vie (de 1 à 365 jours) à sa création : passé ce délai, il répond 401 token_expired, et expires_at dans GET /me indique quand cela arrive (null : sans expiration).

Authorization: Bearer rsk_...

Autorisations (scopes)

Un jeton porte un ensemble d’autorisations. Elles sont indépendantes : keys n’implique pas read. GET /me fonctionne avec n’importe quel jeton valide. Sans l’autorisation requise, la réponse est 403 forbidden_scope.

L’autorisation de chaque méthode est indiquée dans la référence .

Liste d’IP autorisées

Un jeton peut être restreint à une liste d’adresses IPv4/IPv6 ou de plages CIDR (jusqu’à 20). Une requête provenant d’une autre adresse reçoit 403 ip_not_allowed. La liste se définit à la création du jeton.

Limite de débit

20 requêtes par seconde par jeton et 100 par seconde par adresse IP source. En cas de dépassement : 429 rate_limited et un en-tête Retry-After. Attendez ce nombre de secondes, puis réessayez.

Erreurs

Chaque erreur a la même forme. Le même identifiant est envoyé dans l’en-tête X-Request-Id : communiquez-le au support.

{
"error": {
"code": "insufficient_balance",
"message": "Not enough free reseller balance for this key.",
"request_id": "req_..."
}
}

Raisonnez sur error.code, pas sur le texte du message.

Idempotence

Les méthodes qui dépensent de l’argent exigent l’en-tête Idempotency-Key (de 1 à 128 caractères imprimables) ; sans lui (ou avec une valeur inadaptée), la réponse est 400 idempotency_key_required. Elles sont signalées dans la référence. Répéter une requête avec la même clé et le même corps (par revendeur) ne dépense jamais deux fois et renvoie le même objet, y compris le secret de la clé créée par cet appel : une réponse perdue en route peut être récupérée en répétant l’appel. La même clé avec un autre corps donne 409 idempotency_key_reused. Utilisez une nouvelle clé pour chaque nouveau paiement ou commande ; pour POST /orders, l’identité est external_order_id. L’en-tête est facultatif (et pris en compte s’il est envoyé) sur PATCH /keys/{id} (un extend_days/extend_hours répété prolonge une seule fois), POST /plans et POST /webhooks (une répétition renvoie le même objet ; le secret d’un webhook n’est pas affiché de nouveau).

curl -s -X POST https://app.oneprovider.dev/partner/v1/keys \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"client-1","limit_usd":"10.00"}'

Conservez la clé d’idempotence avec votre propre enregistrement de commande, afin qu’après une erreur réseau vous répétiez exactement la même requête.

Pagination

Les endpoints de liste acceptent ?limit=1..100 (50 par défaut) et &cursor=. La réponse est {"items": [...], "next": "<cursor>"} ; next vaut null sur la dernière page. Le curseur est opaque : renvoyez-le tel quel.

curl -s "https://app.oneprovider.dev/partner/v1/keys?limit=100&cursor=<next from the previous page>" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

Bac à sable

Les jetons de test rsk_test_... arrivent bientôt. Pour l’instant, un tel jeton reçoit 501 sandbox_not_implemented.