Partner Open API Guide

Once you are an approved QCode partner, manage your reseller account programmatically with an access token: check balance and usage, create and toggle the sub API Keys you resell. Covers the prerequisite, how to apply, auth, endpoint reference, rate limits and security.

Partner Open API Guide¶

The QCode Partner Open API lets you manage your reseller account programmatically — check balance and usage, create and manage the sub API Keys you resell — so you can integrate provisioning, reconciliation and key issuance into your own systems instead of using the web panel by hand.

⚠️ Prerequisite: you must first be an approved partner. This API is available only to approved QCode partners. If you are not a partner yet, apply first; once approved you can generate an access token and call the API.

1. What this API does¶

As a QCode partner you have a reseller account (prepaid balance, tier-based discount multiplier) and can create multiple sub API Keys to resell to your own customers or team, each with its own quota. The Open API exposes those panel capabilities as REST endpoints:

• Read — account balance and usage, daily spend over the last 7 / 30 days, list all sub API Keys with their per-key cost.
• Write — create a sub API Key (plaintext returned once), enable / disable a sub API Key, update a key's quota and concurrency.

Best for partners who want to wire key issuance / reconciliation into their own billing system, provision keys for downstream customers automatically, or pull usage for monitoring.

2. How to become a partner (prerequisite)¶

This API is only usable once your partner access is approved.

• Not a partner yet → visit Partner Program to review tiers and pricing, then apply via the "How to apply" section (email hi@qcode.cc). Once approved, your account is activated as a partner.
• Already a partner → sign in to the Partner Dashboard.

Onboarding involves a prepaid top-up and a partner tier (A–E, each with a different discount multiplier); see the Partner Program page for details. Calling this API on a non-activated account returns 403.

3. Quick start: get an access token¶

After approval:

1. Sign in to qcode.cc → open the Partner Dashboard.
2. Open "Open API / Access Token".
3. Click Generate token to get a token like rsk_xxxxxxxx.

🔑 The token is shown in full only once, at generate / reset time — copy and store it securely (we only keep its hash). If lost or leaked, click Reset on the same page to rotate it; the old token stops working immediately.

4. Authentication & base URL¶

curl https://api.r.qcode.cc/api/v1/reseller/balance \
  -H "Authorization: Bearer rsk_xxxxxxxx"

5. Endpoint reference¶

All endpoints are under the /api/v1/reseller/ prefix.

6. Creating a sub API Key¶

Limits are in upstream USD. daily_cost_limit_usd and total_cost_limit_usd must be greater than 0. Pass an Idempotency-Key header to make retries safe (so a timeout retry doesn't mint two keys). The plaintext cr_… key is returned only once — save it and hand it to your customer.

curl -X POST https://api.r.qcode.cc/api/v1/reseller/keys \
  -H "Authorization: Bearer rsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-per-create" \
  -d '{"description":"client-a","daily_cost_limit_usd":5,"total_cost_limit_usd":100,"concurrency_limit":5}'

# → {"ok":true,"data":{"id":"...","name":"...","api_key":"cr_...","warnings":[]}}

Enable / disable, update quota:

# disable
curl -X POST https://api.r.qcode.cc/api/v1/reseller/keys/{id}/disable \
  -H "Authorization: Bearer rsk_xxxxxxxx"

# change daily limit
curl -X PATCH https://api.r.qcode.cc/api/v1/reseller/keys/{id} \
  -H "Authorization: Bearer rsk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"daily_cost_limit_usd":10}'

7. Rate limits¶

These are low-frequency management endpoints, rate-limited to reduce the impact of a leaked token:

• Per token: 60 / minute, 1000 / day.
• Creating keys (POST /keys): 5 / hour per token.
• Exceeding a limit returns HTTP 429 with a Retry-After header (seconds).

8. Responses & errors¶

• Success: {"ok": true, "data": { ... }}
• Error: the matching HTTP status + {"detail": "..."}

9. Security¶

• Treat the access token like a password: keep it server-side, HTTPS only, never commit it to a repo or expose it in the browser.
• If a token leaks → Reset it in the panel immediately (old token dies), and disable affected sub Keys as needed.
• Set sensible total / daily limits on each sub Key you create to bound the loss if a single key leaks.
• The cr_… sub Keys you hand out draw on your account balance — manage and reconcile them carefully.

10. Full reference & support¶

• After approval, the "API Docs" page inside the Partner Dashboard (/reseller/api-docs) is the authoritative, versioned developer reference.
• Not a partner yet? → Learn about and apply to the Partner Program
• Questions? → in-site live chat, or email hi@qcode.cc.