Clés et clients de l’API revendeur

Créez, rechargez, mettez en pause et supprimez des clés API clients, et gérez vos clients via l’API revendeur OneProvider, avec des exemples curl.

Émettez, rechargez, mettez en pause et supprimez des clés clients, et gérez vos clients via l’API revendeur, avec des exemples curl.

Tous les modèles, leurs capacités et leurs tarifs Index de la documentation pour les agents IA : https://oneprovider.dev/docs/llms.txt

L’objet clé

Champs de la clé

Champ	Description
`id`	Identifiant signé opaque, pas un nombre.
`name`, `customer_label`	Nom de la clé et libellé du client (par exemple un pseudo).
`customer_id`	Le client auquel appartient la clé, ou null.
`tail`	Derniers caractères de la clé, pour la reconnaître.
`status`	`active`, `paused`, `expired`, `deleting`
`limit_usd`	Total vendu : dépensé plus restant.
`spent_usd`, `remaining_usd`	Dépensé et restant.
`expires_at`, `created_at`	Expiration et création (UTC). expires_at vaut null pour une clé sans expiration (créée à partir d’un forfait avec expires_never ou d’un lot de codes avec key_expires_never).
`last_used_at`	Toujours null pour l’instant.
`concurrency`	Limite de requêtes parallèles (de 1 à 1000), enregistrée avec la clé, pas encore appliquée.
`dashboard_url`	Un lien de dashboard neutre pour votre client. Ce n’est pas le secret de la clé.

Émettre une clé

POST /keys (autorisation keys ; l’en-tête Idempotency-Key est obligatoire). Obligatoires : name et limit_usd ; facultatifs : expires_days (1..365, 30 par défaut) ou expires_hours (de 1 à 8760, par exemple 1 pour une clé d’une heure ; pas les deux), 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}'

Plusieurs clés identiques d’un coup : POST /keys/bulk avec count (1..50), name_prefix et les mêmes limit_usd, expires_days/expires_hours. Les clés sont nommées {name_prefix}-1 … {name_prefix}-N. La somme totale count x limit_usd est vérifiée d’abord ; si l’appel s’interrompt malgré tout en cours de route, répétez-le avec la même Idempotency-Key : les clés déjà créées sont renvoyées de nouveau et les autres sont émises.

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

Le secret n’est affiché qu’une fois Le champ key n’existe que dans la réponse d’émission (201) et dans une répétition exacte de cet appel avec la même Idempotency-Key. Transmettez-le à votre client et conservez-le immédiatement : le secret ne peut pas être récupéré plus tard, émettez donc une nouvelle clé s’il est perdu. Aucune autre réponse (GET, listes) ni aucun webhook ne contient de secrets.

La limite de la clé est réservée sur le solde revendeur. Si elle ne tient pas dans Disponible (Free, available_usd), la réponse est 409 insufficient_balance ; un nom répété donne 409 name_taken, et l’atteinte du nombre maximal de clés donne 409 key_limit.

Lister et lire

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"

Filtres : status, query (recherche par nom et libellé), customer_id. Consommation quotidienne et par modèle : GET /keys/{id}/usage?days=30 (autorisation read, une fenêtre de 1 à 90 jours, 30 par défaut). La réponse est {"key_id", "days", "items": [{"day", "spend_usd", "requests", "tokens"}], "models": [{"model", "spend_usd", "requests", "tokens"}]} : des jours UTC sans trou (zéros inclus), l’argent avec les mêmes chiffres que la page de consommation de l’espace client, les jetons sont input, output, cache_read, cache_write. La consommation de toutes les clés actives d’un client : GET /customers/{id}/usage (la réponse contient keys, au plus 100 clés lues, et truncated). Quand le prestataire est en panne : 503 provider_unavailable.

Modifier, recharger, mettre en pause

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 dans PATCH est la nouvelle limite totale ; elle ne peut pas descendre sous ce qui est déjà dépensé (400 limit_below_spent). Une augmentation, comme une nouvelle clé, doit tenir dans Disponible (Free). Abaisser la limite remet aussitôt la différence non dépensée dans Disponible. La pause conserve la réserve. Expiration : expires_days/expires_hours la fixent à maintenant + N, extend_days/extend_hours ajoutent N à l’expiration actuelle (à partir de maintenant si elle est passée ; une clé expirée réserve de nouveau son reste, qui doit tenir dans Disponible) ; pas ensemble, et l’expiration ne peut pas se situer à plus de 8760 heures. Avec l’Idempotency-Key facultative, un extend_* répété ne prolonge qu’une fois. Une clé sans expiration (expires_at = null) n’a rien à prolonger : extend_* ne s’applique pas, et expires_* lui donne une durée. La clé d’un client bloqué n’accepte que name et customer_label, tout le reste donne 409 customer_blocked.

Supprimer une clé

bash

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

La réponse est 200 {"state":"deleted"} quand la clé a disparu immédiatement, ou 202 {"state":"deleting"} tant que la suppression est en cours. Le reste non dépensé de la limite retourne aussitôt dans Disponible (Free).

Réémettre une clé

POST /keys/{id}/rotate (autorisation keys ; l’en-tête Idempotency-Key est obligatoire) : un nouveau secret pour le même client, par exemple quand l’ancien a fuité. L’ancien secret cesse de fonctionner immédiatement. Le reste non dépensé et l’expiration passent à la nouvelle clé.

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"

C’est une nouvelle clé avec un nouvel id : l’historique des dépenses reste avec l’ancienne clé (désormais supprimée). La réponse 201 contient l’objet clé, key (le nouveau secret, affiché une fois) et rotated_from (l’id de l’ancienne clé). Erreurs : 404 key_not_found, 409 key_limit, key_exhausted (plus rien de disponible), key_expired (expirée : prolongez-la d’abord), 503 provider_unavailable.

Clients

Un client est votre acheteur. Des clés, des commandes et des codes peuvent lui être rattachés : votre propre identifiant est stocké dans external_id (unique, jusqu’à 64 caractères).

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"

Objet client : id, external_id, name, note, blocked, keys_count, created_at. Modifiez le nom et la note avec PATCH /customers/{id}. Un external_id répété donne 409 customer_exists.

Bloquer un client

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

Le blocage (autorisation keys) met en pause toutes les clés actives du client et marque ce dernier comme blocked: true. L’émission de clés, les commandes et les activations de codes pour ce client répondent 409 customer_blocked. Le déblocage ({"blocked":false}) ne reprend que les clés mises en pause par le blocage : celles que vous avez mises en pause vous-même restent en pause.

Dernière mise à jour: 2026-11-08 Vous avez trouvé un bug ? @Oneproviderhelpbot