Partner API

Use the Partner API when your product team needs to onboard customer organizations programmatically while Quotaflow remains the visible API platform. The API is independent from dashboard user sessions and uses a partner machine token.

Base URL and authentication

export QUOTAFLOW_PARTNER_TOKEN="qfp_your_partner_token"
export QUOTAFLOW_PARTNER_BASE_URL="https://api.quotaflow.ai/partner/v1"

Send the token as a bearer token:

-H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN"

Create and rotate partner machine tokens in Dashboard → Partner → Automation Tokens. The full qfp_... token is shown once; store it in your product secret manager. Choose the smallest scope your automation needs:

Keep partner tokens separate from customer routing keys:

All write requests require an Idempotency-Key header. Use a stable key per operation, such as customer-cust_123-create-v1.

What the API does

The v1 automation loop is intentionally small:

1. Check partner funding with GET /funding.
2. Create or find a customer organization by your own external_customer_id.
3. Allocate a USD hard cap from the partner-funded balance to that customer organization.
4. List allowed model groups for that customer.
5. Create a qf_... customer API key bound to the customer allocation.
6. Read balance and usage for automation, support, and alerts.

Quotaflow does not manage your end-customer pricing, plans, taxes, invoices, or multi-currency settlement. If you want a fully custom commercial layer, build it in your own product and use the Quotaflow customer API key behind it.

Funding

curl "$QUOTAFLOW_PARTNER_BASE_URL/funding" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN"

Example response:

{
  "code": 0,
  "message": "success",
  "data": {
    "reseller_id": 42,
    "available_funding_usd": 250.0,
    "reserved_allocations_usd": 100.0,
    "outstanding_usage_usd": 12.5,
    "top_up_url": "https://app.quotaflow.ai/billing"
  }
}

If you need more funds, create a top-up action URL:

curl -X POST "$QUOTAFLOW_PARTNER_BASE_URL/funding/top-up-sessions" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN" \
  -H "Idempotency-Key: topup-100-2026-07-02" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd":100}'

Create or find a customer organization

Use your own stable customer id in the URL. Repeating the same request with the same external_customer_id returns the existing customer.

curl -X PUT "$QUOTAFLOW_PARTNER_BASE_URL/customers/by-external-id/cust_123" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN" \
  -H "Idempotency-Key: customer-cust_123-create-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme AI",
    "contact_email": "owner@acme.example",
    "initial_allocation_usd": 50
  }'

Example response:

{
  "code": 0,
  "message": "success",
  "data": {
    "external_customer_id": "cust_123",
    "created": true,
    "customer": {
      "id": 101,
      "organization_name": "Acme AI",
      "organization_slug": "partner-42-acme-ai",
      "display_name": "Acme AI",
      "billing_mode": "partner_bill",
      "billing_allocation_mode": "partner_allocated",
      "partner_allocation_cap_usd": 50,
      "partner_allocation_remaining_usd": 50,
      "status": "active"
    }
  }
}

If the partner does not have enough available funding, the API returns PARTNER_FUNDING_INSUFFICIENT with available_funding_usd, required_usd, shortfall_usd, and next_action: top_up_partner_balance.

Manage customer allocation

Increase a customer allocation:

curl -X POST "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/allocations" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN" \
  -H "Idempotency-Key: customer-101-allocation-increase-25" \
  -H "Content-Type: application/json" \
  -d '{"action":"increase","amount_usd":25}'

Set a customer allocation to an exact cap:

curl -X POST "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/allocations" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN" \
  -H "Idempotency-Key: customer-101-allocation-set-75" \
  -H "Content-Type: application/json" \
  -d '{"action":"set_limit","limit_usd":75}'

Read the current balance:

curl "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/balance" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN"

The customer key spends only from the allocation bound to that key. Quotaflow does not silently fall back to a different customer or organization balance.

Create a customer API key

First list the model groups the customer can use:

curl "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/groups" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN"

Then create a customer key. The full qf_... key is returned only on the first successful creation response; idempotent replays return the key preview without the full secret. Store the full key securely.

curl -X POST "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/api-keys" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN" \
  -H "Idempotency-Key: customer-101-key-main-v1" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme production key","group_id":123}'

List existing key previews:

curl "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/api-keys" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN"

Disable a key during rotation or abuse response:

curl -X DELETE "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/api-keys/9001" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN" \
  -H "Idempotency-Key: customer-101-key-9001-disable"

Usage

curl "$QUOTAFLOW_PARTNER_BASE_URL/customers/101/usage?start_time=2026-07-01T00:00:00Z&end_time=2026-07-08T00:00:00Z" \
  -H "Authorization: Bearer $QUOTAFLOW_PARTNER_TOKEN"

Usage returns daily buckets with burn_usd, request count, total tokens, and active API keys.