Chaves e clientes da API de revenda

Crie, recarregue, pause e exclua chaves de clientes e gerencie seus clientes pela API de revenda da OneProvider, com exemplos em curl para cada chamada.

Emita, recarregue, pause e exclua chaves de clientes e gerencie os seus clientes pela API de revendedores, com exemplos em curl.

Todos os modelos, recursos e preços Índice da documentação para agentes de IA: https://oneprovider.dev/docs/llms.txt

O objeto da chave

Campos da chave

Campo	Descrição
`id`	Identificador opaco e assinado, não é um número.
`name`, `customer_label`	Nome da chave e um rótulo do cliente (por exemplo, um apelido).
`customer_id`	O cliente a quem a chave pertence, ou null.
`tail`	Últimos caracteres da chave, para reconhecê-la.
`status`	`active`, `paused`, `expired`, `deleting`
`limit_usd`	Total vendido: gasto mais restante.
`spent_usd`, `remaining_usd`	Gasto e restante.
`expires_at`, `created_at`	Validade e criação (UTC). expires_at é null em uma chave sem validade (criada a partir de um plano com expires_never ou de um lote de códigos com key_expires_never).
`last_used_at`	Sempre null por enquanto.
`concurrency`	Limite de requisições paralelas (de 1 a 1000), guardado com a chave, ainda não aplicado.
`dashboard_url`	Um link de dashboard neutro para o seu cliente. Não é o segredo da chave.

Emitir uma chave

POST /keys (permissão keys; o cabeçalho Idempotency-Key é obrigatório). Obrigatórios: name e limit_usd; opcionais: expires_days (1..365, padrão 30) ou expires_hours (de 1 a 8760, por exemplo 1 para uma chave de uma hora; não os dois), 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}'

Várias chaves idênticas de uma vez: POST /keys/bulk com count (1..50), name_prefix e os mesmos limit_usd, expires_days/expires_hours. As chaves recebem os nomes {name_prefix}-1 … {name_prefix}-N. A soma total count x limit_usd é verificada primeiro; se a chamada ainda assim parar no meio, repita-a com o mesmo Idempotency-Key: as chaves já criadas voltam e o restante é emitido.

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

O segredo é exibido uma única vez O campo key existe apenas na resposta de emissão (201) e em uma repetição exata dessa chamada com o mesmo Idempotency-Key. Entregue-o ao seu cliente e guarde-o na hora: o segredo não pode ser recuperado depois, então emita uma nova chave se ele se perder. Nenhuma outra resposta (GET, listas) nem webhook traz segredos.

O limite da chave é reservado no saldo de revendedor. Se ele não couber em Disponível (Free, available_usd), a resposta é 409 insufficient_balance; um nome repetido dá 409 name_taken, e atingir o número máximo de chaves dá 409 key_limit.

Listar e ler

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 (busca por nome e rótulo), customer_id. Consumo diário e por modelo: GET /keys/{id}/usage?days=30 (permissão read, uma janela de 1 a 90 dias, padrão 30). A resposta é {"key_id", "days", "items": [{"day", "spend_usd", "requests", "tokens"}], "models": [{"model", "spend_usd", "requests", "tokens"}]}: dias UTC sem lacunas (com os zeros), dinheiro com os mesmos números da página de consumo do painel, os tokens são input, output, cache_read, cache_write. O consumo de todas as chaves ativas de um cliente: GET /customers/{id}/usage (a resposta traz keys, no máximo 100 chaves consideradas, e truncated). Quando o provedor está fora do ar: 503 provider_unavailable.

Editar, recarregar, 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 em PATCH é o novo limite total; ele não pode ficar abaixo do que já foi gasto (400 limit_below_spent). Um aumento, como uma chave nova, precisa caber em Disponível (Free). Reduzir o limite devolve na hora a diferença não gasta para Disponível (Free). Pausar mantém a reserva. Validade: expires_days/expires_hours a definem como agora + N, extend_days/extend_hours somam N à validade atual (a partir de agora, se ela já passou; uma chave vencida reserva o restante de novo, e ele precisa caber em Disponível (Free)); não podem ser usados juntos, e a validade não pode ficar a mais de 8760 horas no futuro. Com o Idempotency-Key opcional, um extend_* repetido prorroga uma só vez. Uma chave sem validade (expires_at = null) não tem o que prorrogar: extend_* não se aplica, e expires_* lhe dá um prazo. A chave de um cliente bloqueado aceita apenas name e customer_label; qualquer outra coisa dá 409 customer_blocked.

Excluir uma chave

bash

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

A resposta é 200 {"state":"deleted"} quando a chave some na hora, ou 202 {"state":"deleting"} enquanto a exclusão está em andamento. O restante não gasto do limite volta para Disponível (Free) na hora.

Reemitir uma chave

POST /keys/{id}/rotate (permissão keys; o cabeçalho Idempotency-Key é obrigatório): um novo segredo para o mesmo cliente, por exemplo quando o antigo vazou. O segredo antigo deixa de funcionar imediatamente. O restante não gasto e a validade passam para a nova chave.

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"

Esta é uma chave nova, com um novo id: o histórico de gastos fica com a chave antiga (agora excluída). A resposta 201 contém o objeto da chave, key (o novo segredo, exibido uma vez) e rotated_from (o id da chave antiga). Erros: 404 key_not_found, 409 key_limit, key_exhausted (não sobrou nada), key_expired (venceu: prorrogue antes), 503 provider_unavailable.

Clientes

Um cliente é o seu comprador. Chaves, pedidos e códigos podem ser vinculados a um cliente: o seu próprio identificador fica em external_id (único, até 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 do cliente: id, external_id, name, note, blocked, keys_count, created_at. Edite name e note com PATCH /customers/{id}. Um external_id repetido dá 409 customer_exists.

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

Bloquear (permissão keys) pausa todas as chaves ativas do cliente e marca o cliente com blocked: true. A emissão de chaves, os pedidos e os resgates de códigos em nome dele respondem 409 customer_blocked. Desbloquear ({"blocked":false}) retoma apenas as chaves que o bloqueio pausou: as que você mesmo pausou continuam pausadas.

Última atualização: 2026-11-08 Encontrou um erro? @Oneproviderhelpbot