Chiavi e clienti dell'API rivenditori

Crea, ricarica, sospendi ed elimina le chiavi API dei clienti e gestisci i clienti con l'API rivenditori di OneProvider, con esempi curl per ogni chiamata.

Emetti, ricarica, metti in pausa ed elimina le chiavi dei clienti e gestisci i tuoi clienti con l'API per rivenditori, con esempi curl.

Tutti i modelli, le funzionalità e i prezzi Indice della documentazione per agenti AI: https://oneprovider.dev/docs/llms.txt

L'oggetto chiave

Campi della chiave

Campo	Descrizione
`id`	Identificatore opaco firmato, non un numero.
`name`, `customer_label`	Nome della chiave ed etichetta del cliente (per esempio un nickname).
`customer_id`	Il cliente a cui appartiene la chiave, oppure null.
`tail`	Ultimi caratteri della chiave, per riconoscerla.
`status`	`active`, `paused`, `expired`, `deleting`
`limit_usd`	Totale venduto: speso più residuo.
`spent_usd`, `remaining_usd`	Speso e residuo.
`expires_at`, `created_at`	Scadenza e creazione (UTC). expires_at è null per una chiave senza scadenza (creata da un piano con expires_never o da un lotto di codici con key_expires_never).
`last_used_at`	Per ora sempre null.
`concurrency`	Limite di richieste parallele (da 1 a 1000), salvato con la chiave, non ancora applicato.
`dashboard_url`	Un link alla dashboard neutra per il tuo cliente. Non è il segreto della chiave.

Emettere una chiave

POST /keys (scope keys; l'header Idempotency-Key è obbligatorio). Obbligatori: name e limit_usd; facoltativi: expires_days (1..365, predefinito 30) oppure expires_hours (da 1 a 8760, per esempio 1 per una chiave di un'ora; non entrambi), 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}'

Più chiavi identiche in una volta: POST /keys/bulk con count (1..50), name_prefix e gli stessi limit_usd, expires_days/expires_hours. Le chiavi si chiamano {name_prefix}-1 … {name_prefix}-N. Prima viene controllata l'intera somma count x limit_usd; se la chiamata si ferma comunque a metà, ripetila con la stessa Idempotency-Key: le chiavi già create vengono restituite di nuovo e le altre vengono emesse.

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

Il segreto viene mostrato una sola volta Il campo key esiste solo nella risposta di emissione (201) e in una ripetizione identica di quella chiamata con la stessa Idempotency-Key. Consegnalo al tuo cliente e conservalo subito: il segreto non si può recuperare in seguito, quindi se lo perdi emetti una nuova chiave. Nessun'altra risposta (GET, elenchi) né webhook contiene segreti.

Il limite della chiave viene riservato sul saldo da rivenditore. Se non rientra in Disponibile (Free, available_usd), la risposta è 409 insufficient_balance; un nome ripetuto dà 409 name_taken, e raggiungere il massimo di chiavi dà 409 key_limit.

Elenco e lettura

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"

Filtri: status, query (ricerca per nome ed etichetta), customer_id. Consumo giornaliero e per modello: GET /keys/{id}/usage?days=30 (scope read, una finestra da 1 a 90 giorni, predefinita 30). La risposta è {"key_id", "days", "items": [{"day", "spend_usd", "requests", "tokens"}], "models": [{"model", "spend_usd", "requests", "tokens"}]}: giorni UTC senza buchi (zeri compresi), importi con le stesse cifre della pagina Consumo dell'area personale, i token sono input, output, cache_read, cache_write. Il consumo di tutte le chiavi attive di un cliente: GET /customers/{id}/usage (la risposta contiene keys, al massimo 100 chiavi considerate, e truncated). Quando il provider non è disponibile: 503 provider_unavailable.

Modificare, ricaricare, mettere in pausa

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 è il nuovo limite totale; non può scendere sotto quanto è già stato speso (400 limit_below_spent). Un aumento, come una nuova chiave, deve rientrare in Disponibile (Free). Abbassare il limite restituisce subito a Disponibile la differenza non spesa. La pausa mantiene la riserva. Scadenza: expires_days/expires_hours la impostano a adesso + N, extend_days/extend_hours aggiungono N alla scadenza attuale (da adesso, se è già passata; una chiave scaduta riserva di nuovo il suo residuo, che deve rientrare in Disponibile); non insieme tra loro, e la scadenza non può essere oltre 8760 ore da adesso. Con l'Idempotency-Key facoltativa un extend_* ripetuto prolunga una volta sola. Una chiave senza scadenza (expires_at = null) non ha nulla da prolungare: extend_* non si applica, ed expires_* le assegna una durata. La chiave di un cliente bloccato accetta solo name e customer_label, qualsiasi altra cosa dà 409 customer_blocked.

Eliminare una chiave

bash

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

La risposta è 200 {"state":"deleted"} quando la chiave è stata eliminata subito, oppure 202 {"state":"deleting"} mentre l'eliminazione è in corso. Il residuo non speso del limite torna subito a Disponibile.

Riemettere una chiave (rotate)

POST /keys/{id}/rotate (scope keys; l'header Idempotency-Key è obbligatorio): un nuovo segreto per lo stesso cliente, per esempio quando il vecchio è trapelato. Il vecchio segreto smette di funzionare subito. Il residuo non speso e la scadenza passano alla nuova chiave.

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"

È una nuova chiave con un nuovo id: la cronologia della spesa resta con la vecchia chiave (ora eliminata). La risposta 201 contiene l'oggetto chiave, key (il nuovo segreto, mostrato una sola volta) e rotated_from (l'id della vecchia chiave). Errori: 404 key_not_found, 409 key_limit, key_exhausted (non è rimasto nulla), key_expired (scaduta: prima prolungala), 503 provider_unavailable.

Clienti

Un cliente è il tuo acquirente. Chiavi, ordini e codici possono essere collegati a un cliente: il tuo identificatore è salvato in external_id (univoco, fino a 64 caratteri).

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"

Oggetto cliente: id, external_id, name, note, blocked, keys_count, created_at. Modifica nome e nota con PATCH /customers/{id}. Un external_id ripetuto dà 409 customer_exists.

Bloccare un cliente

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

Il blocco (scope keys) mette in pausa tutte le chiavi attive del cliente e segna il cliente come blocked: true. Emissione di chiavi, ordini e riscatti di codici a suo nome rispondono 409 customer_blocked. Lo sblocco ({"blocked":false}) riattiva solo le chiavi messe in pausa dal blocco: quelle che hai messo in pausa tu restano in pausa.

Ultimo aggiornamento: 2026-11-08 Hai trovato un errore? @Oneproviderhelpbot