Reseller-API: Authentifizierung und Limits

Bearer-Tokens, Scopes, IP-Allowlist, Rate-Limit, Fehlercodes, Idempotency-Keys und Paginierung der Reseller-API.

Tokens

Ein Token sieht aus wie rsk_ gefolgt von 40 Zeichen. Sie erstellen ihn im Konto (Reiter „Reseller“, „API & Einstellungen“); der Wert wird nur einmal angezeigt, wir speichern nur einen Hash und die letzten 4 Zeichen. Sie können bis zu 10 aktive Tokens haben und jeden davon jederzeit widerrufen. Beim Erstellen lässt sich für einen Token eine Lebensdauer (1 bis 365 Tage) festlegen: Danach antwortet der Token mit 401 token_expired, und expires_at in GET /me nennt den Zeitpunkt (null: unbefristet).

Authorization: Bearer rsk_...

Scopes

Ein Token trägt eine Menge von Scopes. Scopes sind voneinander unabhängig: keys schließt read nicht ein. GET /me funktioniert mit jedem gültigen Token. Fehlt der erforderliche Scope, lautet die Antwort 403 forbidden_scope.

Der Scope jeder Methode steht in der Referenz .

IP-Allowlist

Ein Token lässt sich auf eine Liste von IPv4-/IPv6-Adressen oder CIDR-Bereichen beschränken (bis zu 20). Eine Anfrage von einer anderen Adresse erhält 403 ip_not_allowed. Die Liste wird beim Erstellen des Tokens festgelegt.

Rate-Limit

20 Anfragen pro Sekunde und Token sowie 100 pro Sekunde und Quell-IP-Adresse. Bei Überschreitung: 429 rate_limited und ein Header Retry-After. Warten Sie so viele Sekunden und versuchen Sie es erneut.

Fehler

Jeder Fehler hat dieselbe Form. Dieselbe id wird im Header X-Request-Id mitgesendet: Nennen Sie sie dem Support.

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

Verzweigen Sie nach error.code, nicht nach dem Meldungstext.

Idempotenz

Methoden, die Geld ausgeben, erfordern den Header Idempotency-Key (1 bis 128 druckbare Zeichen); ohne ihn (oder mit einem ungeeigneten) lautet die Antwort 400 idempotency_key_required. Sie sind in der Referenz markiert. Wird eine Anfrage mit demselben Key und demselben Body (pro Reseller) wiederholt, wird nie doppelt Geld ausgegeben, und Sie erhalten dasselbe Objekt zurück, einschließlich des Secrets des Schlüssels, den dieser Aufruf erstellt hat: Eine unterwegs verlorene Antwort lässt sich durch Wiederholen des Aufrufs wiederherstellen. Derselbe Key mit einem anderen Body ergibt 409 idempotency_key_reused. Verwenden Sie für jede neue Zahlung oder Bestellung einen neuen Key; bei POST /orders übernimmt external_order_id diese Rolle. Der Header ist bei PATCH /keys/{id} (ein wiederholtes extend_days/extend_hours verlängert nur einmal), POST /plans und POST /webhooks optional (und wird berücksichtigt, wenn er gesendet wird; eine Wiederholung liefert dasselbe Objekt, das Webhook-Secret wird nicht erneut angezeigt).

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"}'

Speichern Sie den Idempotency-Key zusammen mit Ihrem eigenen Bestelldatensatz, damit Sie nach einem Netzwerkfehler genau dieselbe Anfrage wiederholen.

Paginierung

Listen-Endpoints akzeptieren ?limit=1..100 (Standard 50) und &cursor=. Die Antwort ist {"items": [...], "next": "<cursor>"}; next ist auf der letzten Seite null. Der Cursor ist opak: Geben Sie ihn unverändert zurück.

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

Sandbox

Test-Tokens rsk_test_... kommen bald. Vorerst erhält ein solcher Token 501 sandbox_not_implemented.