Reseller-API: Schlüssel und Kunden

Kunden-API-Schlüssel anlegen, aufladen, pausieren, löschen und Kunden verwalten – über die OneProvider-Reseller-API, mit curl-Beispielen für jeden Aufruf.

Kundenschlüssel ausstellen, aufladen, pausieren und löschen sowie Ihre Kunden über die Reseller-API verwalten, mit curl-Beispielen.

Alle Modelle, Funktionen und Preise Dokumentationsindex für KI-Agenten: https://oneprovider.dev/docs/llms.txt

Das Schlüsselobjekt

Felder des Schlüssels

Feld	Beschreibung
`id`	Opake signierte Kennung, keine Zahl.
`name`, `customer_label`	Name des Schlüssels und eine Kundenkennzeichnung (zum Beispiel ein Spitzname).
`customer_id`	Der Kunde, zu dem der Schlüssel gehört, oder null.
`tail`	Letzte Zeichen des Schlüssels, zum Wiedererkennen.
`status`	`active`, `paused`, `expired`, `deleting`
`limit_usd`	Insgesamt verkauft: Verbrauch plus Rest.
`spent_usd`, `remaining_usd`	Verbraucht und verbleibend.
`expires_at`, `created_at`	Ablauf und Erstellung (UTC). expires_at ist null bei einem unbefristeten Schlüssel (aus einem Tarif mit expires_never oder einer Code-Charge mit key_expires_never).
`last_used_at`	Vorerst immer null.
`concurrency`	Limit paralleler Anfragen (1 bis 1000), wird mit dem Schlüssel gespeichert, aber noch nicht durchgesetzt.
`dashboard_url`	Ein neutraler Dashboard-Link für Ihren Kunden. Er ist nicht das Secret des Schlüssels.

Einen Schlüssel ausstellen

POST /keys (Scope keys; der Header Idempotency-Key ist erforderlich). Pflicht: name und limit_usd; optional: expires_days (1..365, Standard 30) oder expires_hours (1 bis 8760, zum Beispiel 1 für einen einstündigen Schlüssel; nicht beide), customer_id, customer_label, concurrency.

bash

curl -s -X POST https://app.oneprovider.dev/partner/v1/keys \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: key-anna-001" \
-H "Content-Type: application/json" \
-d '{"name":"anna-main","limit_usd":"25.00","expires_days":30,"customer_label":"Anna"}'
# a one-hour key
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys -H "Authorization: Bearer $OP_PARTNER_TOKEN" -H "Idempotency-Key: key-trial-001" -H "Content-Type: application/json" -d '{"name":"trial","limit_usd":"1.00","expires_hours":1}'

Mehrere identische Schlüssel auf einmal: POST /keys/bulk mit count (1..50), name_prefix und demselben limit_usd, expires_days/expires_hours. Die Schlüssel heißen {name_prefix}-1 … {name_prefix}-N. Zuerst wird die Gesamtsumme count × limit_usd geprüft; bricht der Aufruf dennoch auf halbem Weg ab, wiederholen Sie ihn mit demselben Idempotency-Key: Die bereits erstellten Schlüssel kommen erneut zurück, die übrigen werden ausgestellt.

json

{
"id": "<key id>",
"name": "anna-main",
"customer_label": "Anna",
"status": "active",
"limit_usd": "25.00",
"spent_usd": "0.00",
"remaining_usd": "25.00",
"expires_at": "2026-11-07T12:00:00Z",
"dashboard_url": "<dashboard link>",
"key": "sk-..."
}

Das Secret wird nur einmal angezeigt Das Feld key gibt es nur in der Antwort auf das Ausstellen (201) und in einer exakten Wiederholung dieses Aufrufs mit demselben Idempotency-Key. Geben Sie es sofort an Ihren Kunden weiter und speichern Sie es: Das Secret lässt sich später nicht abrufen, stellen Sie bei Verlust einen neuen Schlüssel aus. Keine andere Antwort (GET, Listen) und kein Webhook enthält Secrets.

Das Schlüssellimit wird auf dem Reseller-Guthaben reserviert. Passt es nicht in „Verfügbar“ (available_usd), lautet die Antwort 409 insufficient_balance; ein doppelter Name ergibt 409 name_taken, und das Erreichen der maximalen Schlüsselzahl ergibt 409 key_limit.

Auflisten und lesen

bash

# active keys of one customer
curl -s "https://app.oneprovider.dev/partner/v1/keys?status=active&customer_id=<customer id>&limit=50" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"
# one key (no secret) with dashboard_url
curl -s https://app.oneprovider.dev/partner/v1/keys/<key id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

Filter: status, query (Suche nach Name und Kennzeichnung), customer_id. Verbrauch pro Tag und pro Modell: GET /keys/{id}/usage?days=30 (Scope read, ein Fenster von 1 bis 90 Tagen, Standard 30). Die Antwort ist {"key_id", "days", "items": [{"day", "spend_usd", "requests", "tokens"}], "models": [{"model", "spend_usd", "requests", "tokens"}]}: UTC-Tage ohne Lücken (einschließlich Nullen), Geld in denselben Zahlen wie auf der Verbrauchsseite des Kontos, Tokens sind input, output, cache_read, cache_write. Der Verbrauch aller aktiven Schlüssel eines Kunden: GET /customers/{id}/usage (die Antwort enthält keys, höchstens 100 gelesene Schlüssel, und truncated). Ist der Anbieter nicht erreichbar: 503 provider_unavailable.

Bearbeiten, aufladen, pausieren

bash

# change the limit / expiry / name / label / concurrency
curl -s -X PATCH https://app.oneprovider.dev/partner/v1/keys/<key id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"limit_usd":"40.00"}'
# add 10.00 USD to the key limit
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/topup \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: topup-anna-001" \
-H "Content-Type: application/json" \
-d '{"amount_usd":"10.00"}'
# pause and resume
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/pause -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/resume -H "Authorization: Bearer $OP_PARTNER_TOKEN"

limit_usd in PATCH ist das neue Gesamtlimit; es darf nicht unter dem bereits Verbrauchten liegen (400 limit_below_spent). Eine Erhöhung muss wie ein neuer Schlüssel in „Verfügbar“ passen. Das Senken des Limits gibt die nicht verbrauchte Differenz sofort an „Verfügbar“ zurück. Beim Pausieren bleibt die Reserve bestehen. Laufzeit: expires_days/expires_hours setzen sie auf jetzt + N, extend_days/extend_hours addieren N zur aktuellen Laufzeit (ab jetzt, wenn sie abgelaufen ist; ein abgelaufener Schlüssel reserviert seinen Rest erneut, und der muss in „Verfügbar“ passen); nicht gemeinsam, und die Laufzeit darf nicht mehr als 8760 Stunden in der Zukunft liegen. Mit dem optionalen Idempotency-Key verlängert ein wiederholtes extend_* nur einmal. Ein unbefristeter Schlüssel (expires_at = null) hat nichts zu verlängern: extend_* gilt nicht, und expires_* gibt ihm eine Laufzeit. Der Schlüssel eines gesperrten Kunden nimmt nur name und customer_label an, alles andere ergibt 409 customer_blocked.

Einen Schlüssel löschen

bash

curl -s -X DELETE https://app.oneprovider.dev/partner/v1/keys/<key id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

Die Antwort ist 200 {"state":"deleted"}, wenn der Schlüssel sofort weg ist, oder 202 {"state":"deleting"}, solange das Löschen läuft. Der nicht verbrauchte Rest des Limits geht sofort an „Verfügbar“ zurück.

Einen Schlüssel rotieren

POST /keys/{id}/rotate (Scope keys; der Header Idempotency-Key ist erforderlich): ein neues Secret für denselben Kunden, zum Beispiel wenn das alte durchgesickert ist. Das alte Secret funktioniert sofort nicht mehr. Der nicht verbrauchte Rest und die Laufzeit gehen auf den neuen Schlüssel über.

bash

curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/rotate \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: rotate-anna-001"

Das ist ein neuer Schlüssel mit einer neuen id: Der Verbrauchsverlauf bleibt beim alten (nun gelöschten) Schlüssel. Die Antwort 201 enthält das Schlüsselobjekt, key (das neue Secret, nur einmal angezeigt) und rotated_from (die id des alten Schlüssels). Fehler: 404 key_not_found, 409 key_limit, key_exhausted (nichts mehr übrig), key_expired (abgelaufen: zuerst verlängern), 503 provider_unavailable.

Kunden

Ein Kunde ist Ihr Käufer. Schlüssel, Bestellungen und Codes lassen sich mit einem Kunden verknüpfen: Ihre eigene Kennung wird in external_id gespeichert (eindeutig, bis zu 64 Zeichen).

bash

curl -s -X POST https://app.oneprovider.dev/partner/v1/customers \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"external_id":"user-77","name":"Anna","note":"from the Telegram shop"}'
curl -s "https://app.oneprovider.dev/partner/v1/customers?external_id=user-77" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

Kundenobjekt: id, external_id, name, note, blocked, keys_count, created_at. Name und Notiz bearbeiten Sie mit PATCH /customers/{id}. Eine wiederholte external_id ergibt 409 customer_exists.

Einen Kunden sperren

bash

curl -s -X PATCH https://app.oneprovider.dev/partner/v1/customers/<customer id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"blocked":true}'

Das Sperren (Scope keys) pausiert alle aktiven Schlüssel des Kunden und markiert sie mit blocked: true. Das Ausstellen von Schlüsseln, Bestellungen und Code-Einlösungen für ihn wird mit 409 customer_blocked abgelehnt. Das Entsperren ({"blocked":false}) setzt nur die Schlüssel fort, die die Sperre pausiert hat: Schlüssel, die Sie selbst pausiert haben, bleiben pausiert.

Zuletzt aktualisiert: 2026-11-08 Fehler gefunden? @Oneproviderhelpbot