Klucze i klienci w API resellera

Twórz, doładowuj, wstrzymuj i usuwaj klucze API klientów oraz zarządzaj klientami przez API resellera OneProvider, z przykładami curl dla każdego wywołania.

Wydawanie, doładowywanie, wstrzymywanie i usuwanie kluczy klientów oraz zarządzanie klientami przez API resellera, z przykładami curl.

Wszystkie modele, możliwości i ceny Indeks dokumentacji dla agentów AI: https://oneprovider.dev/docs/llms.txt

Obiekt klucza

Pola klucza

Pole	Opis
`id`	Nieprzezroczysty podpisany identyfikator, nie liczba.
`name`, `customer_label`	Nazwa klucza i etykieta klienta (na przykład pseudonim).
`customer_id`	Klient, do którego należy klucz, lub null.
`tail`	Ostatnie znaki klucza, do rozpoznawania.
`status`	`active`, `paused`, `expired`, `deleting`
`limit_usd`	Łącznie sprzedane: wydane plus pozostałe.
`spent_usd`, `remaining_usd`	Wydane i pozostałe.
`expires_at`, `created_at`	Wygaśnięcie i utworzenie (UTC). expires_at ma wartość null dla klucza bez terminu ważności (z planu z expires_never lub partii kodów z key_expires_never).
`last_used_at`	Na razie zawsze null.
`concurrency`	Limit równoległych żądań (od 1 do 1000), zapisywany z kluczem, na razie nie jest egzekwowany.
`dashboard_url`	Neutralny link do panelu dla twojego klienta. To nie jest sekret klucza.

Wydanie klucza

POST /keys (uprawnienie keys; wymagany jest nagłówek Idempotency-Key). Wymagane: name i limit_usd; opcjonalne: expires_days (1..365, domyślnie 30) lub expires_hours (od 1 do 8760, na przykład 1 dla klucza na godzinę; nie oba naraz), 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}'

Kilka identycznych kluczy naraz: POST /keys/bulk z count (1..50), name_prefix i takimi samymi limit_usd, expires_days/expires_hours. Klucze mają nazwy {name_prefix}-1 … {name_prefix}-N. Najpierw sprawdzana jest cała suma count x limit_usd; jeśli wywołanie mimo to zatrzyma się w połowie, powtórz je z tym samym Idempotency-Key: już utworzone klucze wrócą ponownie, a pozostałe zostaną wydane.

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

Sekret widać tylko raz Pole key występuje tylko w odpowiedzi na wydanie (201) i w dokładnym powtórzeniu tego wywołania z tym samym Idempotency-Key. Przekaż je klientowi i od razu zapisz: sekretu nie da się odzyskać później, a w razie utraty trzeba wydać nowy klucz. Żadna inna odpowiedź (GET, listy) ani webhook nie zawiera sekretów.

Limit klucza jest rezerwowany na saldzie resellera. Jeśli nie mieści się w pozycji Dostępne (available_usd), odpowiedź to 409 insufficient_balance; powtórzona nazwa daje 409 name_taken, a osiągnięcie maksymalnej liczby kluczy daje 409 key_limit.

Lista i odczyt

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"

Filtry: status, query (wyszukiwanie po nazwie i etykiecie), customer_id. Zużycie dzienne i według modeli: GET /keys/{id}/usage?days=30 (uprawnienie read, okno od 1 do 90 dni, domyślnie 30). Odpowiedź ma postać {"key_id", "days", "items": [{"day", "spend_usd", "requests", "tokens"}], "models": [{"model", "spend_usd", "requests", "tokens"}]}: dni UTC bez luk (łącznie z zerami), pieniądze w tych samych liczbach co na stronie zużycia w Panelu, tokeny to input, output, cache_read, cache_write. Zużycie wszystkich działających kluczy klienta: GET /customers/{id}/usage (odpowiedź zawiera keys, najwyżej 100 odczytanych kluczy, oraz truncated). Gdy dostawca nie działa: 503 provider_unavailable.

Edycja, doładowanie, wstrzymanie

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 w PATCH to nowy łączny limit; nie może być niższy niż już wydana kwota (400 limit_below_spent). Podwyższenie, podobnie jak nowy klucz, musi się zmieścić w pozycji Dostępne. Obniżenie limitu natychmiast zwraca niewykorzystaną różnicę do pozycji Dostępne. Wstrzymanie zachowuje rezerwę. Termin ważności: expires_days/expires_hours ustawiają go na teraz + N, extend_days/extend_hours dodają N do bieżącego terminu (od teraz, jeśli już minął; wygasły klucz ponownie rezerwuje swoją resztę, która musi się zmieścić w pozycji Dostępne); nie można ich łączyć ze sobą, a termin nie może wypadać dalej niż 8760 godzin w przód. Z opcjonalnym Idempotency-Key powtórzone extend_* przedłuża tylko raz. Klucz bez terminu ważności (expires_at = null) nie ma czego przedłużać: extend_* nie ma zastosowania, a expires_* nadaje mu termin. Klucz zablokowanego klienta przyjmuje tylko name i customer_label, wszystko inne to 409 customer_blocked.

Usunięcie klucza

bash

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

Odpowiedź to 200 {"state":"deleted"}, gdy klucz zniknął od razu, lub 202 {"state":"deleting"}, gdy usuwanie trwa. Niewykorzystana reszta limitu natychmiast wraca do pozycji Dostępne.

Rotacja klucza

POST /keys/{id}/rotate (uprawnienie keys; wymagany jest nagłówek Idempotency-Key): nowy sekret dla tego samego klienta, na przykład gdy stary wyciekł. Stary sekret przestaje działać natychmiast. Niewykorzystana reszta i termin ważności przechodzą na nowy klucz.

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"

To nowy klucz z nowym id: historia wydatków zostaje przy starym (już usuniętym) kluczu. Odpowiedź 201 zawiera obiekt klucza, key (nowy sekret, widoczny tylko raz) i rotated_from (id starego klucza). Błędy: 404 key_not_found, 409 key_limit, key_exhausted (nic nie zostało), key_expired (wygasł: najpierw go przedłuż), 503 provider_unavailable.

Klienci

Klient to twój kupujący. Można z nim powiązać klucze, zamówienia i kody: twój własny identyfikator jest zapisany w external_id (unikalny, do 64 znaków).

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"

Obiekt klienta: id, external_id, name, note, blocked, keys_count, created_at. Nazwę i notatkę edytujesz przez PATCH /customers/{id}. Powtórzone external_id daje 409 customer_exists.

Zablokowanie klienta

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

Blokada (uprawnienie keys) wstrzymuje wszystkie działające klucze klienta i oznacza je blocked: true. Wydawanie kluczy, zamówienia i aktywacje kodów dla tego klienta odpowiadają 409 customer_blocked. Odblokowanie ({"blocked":false}) wznawia tylko klucze wstrzymane przez blokadę: klucze wstrzymane ręcznie pozostają wstrzymane.

Ostatnia aktualizacja: 2026-11-08 Widzisz błąd? @Oneproviderhelpbot