Claves y clientes de la API de revendedores

Crea, recarga, pausa y elimina claves de clientes y gestiona a tus clientes con la API de revendedores de OneProvider, con ejemplos curl de cada llamada.

Emite, recarga, pausa y elimina claves de clientes y gestiona a tus clientes con la API de revendedores, con ejemplos en curl.

Todos los modelos, capacidades y precios Índice de la documentación para agentes de IA: https://oneprovider.dev/docs/llms.txt

El objeto clave

Campos de la clave

Campo	Descripción
`id`	Identificador opaco firmado, no un número.
`name`, `customer_label`	Nombre de la clave y una etiqueta del cliente (por ejemplo, un apodo).
`customer_id`	El cliente al que pertenece la clave, o null.
`tail`	Últimos caracteres de la clave, para reconocerla.
`status`	`active`, `paused`, `expired`, `deleting`
`limit_usd`	Total vendido: gastado más restante.
`spent_usd`, `remaining_usd`	Gastado y restante.
`expires_at`, `created_at`	Vencimiento y creación (UTC). expires_at es null en una clave sin vencimiento (creada a partir de un plan con expires_never o de un lote de códigos con key_expires_never).
`last_used_at`	Por ahora siempre null.
`concurrency`	Límite de solicitudes en paralelo (de 1 a 1000), se guarda con la clave, aún no se aplica.
`dashboard_url`	Un enlace de dashboard neutro para tu cliente. No es el secreto de la clave.

Emitir una clave

POST /keys (permiso keys; el encabezado Idempotency-Key es obligatorio). Obligatorios: name y limit_usd; opcionales: expires_days (1..365, por defecto 30) o expires_hours (de 1 a 8760, por ejemplo 1 para una clave de una hora; no ambos), 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}'

Varias claves idénticas a la vez: POST /keys/bulk con count (1..50), name_prefix y los mismos limit_usd, expires_days/expires_hours. Las claves se llaman {name_prefix}-1 … {name_prefix}-N. Primero se comprueba la suma total count × limit_usd; si la llamada se detiene a medias, repítela con el mismo Idempotency-Key: las claves ya creadas vuelven a devolverse y se emiten las que faltan.

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

El secreto se muestra una sola vez El campo key existe solo en la respuesta de emisión (201) y en una repetición exacta de esa llamada con el mismo Idempotency-Key. Entrégalo a tu cliente y guárdalo de inmediato: el secreto no se puede recuperar después, así que si se pierde, emite una clave nueva. Ninguna otra respuesta (GET, listas) ni webhook lleva secretos.

El límite de la clave se reserva en el saldo de revendedor. Si no cabe en Disponible (Free, available_usd), la respuesta es 409 insufficient_balance; un nombre repetido da 409 name_taken, y al alcanzar el máximo de claves da 409 key_limit.

Listar y leer

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"

Filtros: status, query (búsqueda por nombre y etiqueta), customer_id. Consumo diario y por modelo: GET /keys/{id}/usage?days=30 (permiso read, una ventana de 1 a 90 días, por defecto 30). La respuesta es {"key_id", "days", "items": [{"day", "spend_usd", "requests", "tokens"}], "models": [{"model", "spend_usd", "requests", "tokens"}]}: días UTC sin huecos (incluidos los ceros), dinero con las mismas cifras que la página de consumo del panel, los tokens son input, output, cache_read, cache_write. El consumo de todas las claves activas de un cliente: GET /customers/{id}/usage (la respuesta incluye keys, se leen como máximo 100 claves, y truncated). Si el proveedor no responde: 503 provider_unavailable.

Editar, recargar, pausar

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 en PATCH es el nuevo límite total; no puede bajar de lo que ya se gastó (400 limit_below_spent). Un aumento, igual que una clave nueva, tiene que caber en Disponible (Free). Al bajar el límite, la diferencia sin gastar vuelve a Disponible (Free) de inmediato. Pausar mantiene la reserva. Vencimiento: expires_days/expires_hours lo fijan en ahora + N, extend_days/extend_hours suman N al vencimiento actual (desde ahora si ya pasó; una clave vencida vuelve a reservar su resto, que debe caber en Disponible); no se pueden combinar entre sí, y el vencimiento no puede quedar a más de 8760 horas en el futuro. Con el Idempotency-Key opcional, un extend_* repetido amplía una sola vez. Una clave sin vencimiento (expires_at = null) no tiene nada que ampliar: extend_* no se aplica, y expires_* le da un plazo. La clave de un cliente bloqueado admite solo name y customer_label; cualquier otra cosa da 409 customer_blocked.

Eliminar una clave

bash

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

La respuesta es 200 {"state":"deleted"} cuando la clave se elimina al instante, o 202 {"state":"deleting"} mientras la eliminación está en curso. El resto sin gastar del límite vuelve a Disponible (Free) de inmediato.

Rotar una clave

POST /keys/{id}/rotate (permiso keys; el encabezado Idempotency-Key es obligatorio): un secreto nuevo para el mismo cliente, por ejemplo cuando se filtró el anterior. El secreto anterior deja de funcionar al instante. El resto sin gastar y el vencimiento pasan a la clave nueva.

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"

Es una clave nueva con un id nuevo: el historial de gasto se queda con la clave anterior (ahora eliminada). La respuesta 201 contiene el objeto clave, key (el secreto nuevo, que se muestra una sola vez) y rotated_from (el id de la clave anterior). Errores: 404 key_not_found, 409 key_limit, key_exhausted (no queda nada), key_expired (venció: amplía primero su plazo), 503 provider_unavailable.

Clientes

Un cliente es tu comprador. Se le pueden vincular claves, pedidos y códigos: tu propio identificador se guarda en external_id (único, hasta 64 caracteres).

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"

Objeto cliente: id, external_id, name, note, blocked, keys_count, created_at. Edita el nombre y la nota con PATCH /customers/{id}. Un external_id repetido da 409 customer_exists.

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

El bloqueo (permiso keys) pausa todas las claves activas del cliente y las marca con blocked: true. La emisión de claves, los pedidos y los canjes de códigos a su nombre responden 409 customer_blocked. Al desbloquear ({"blocked":false}) se reanudan solo las claves que pausó el bloqueo: las que pausaste tú siguen en pausa.

Última actualización: 2026-11-08 ¿Encontraste un error? @Oneproviderhelpbot