# 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](https://qcode.cc/partner-program); 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](https://qcode.cc/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](https://qcode.cc/reseller/dashboard).

> Onboarding involves a prepaid top-up and a partner tier (A–E, each with a different discount multiplier); see the [Partner Program](https://qcode.cc/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](https://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

| Item | Value |
|---|---|
| Base URL (recommended) | `https://api.r.qcode.cc` |
| Fallback | `https://qcode.cc` (same API) |
| Auth | Header `Authorization: Bearer rsk_xxxxxxxx` |
| Write body | JSON, with `Content-Type: application/json` |

```bash
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.

| Method | Path | Description |
|---|---|---|
| GET | `/api/v1/reseller/me` | Account summary (tier, region, currency, status) |
| GET | `/api/v1/reseller/balance` | Balance and usage (your settlement currency) |
| GET | `/api/v1/reseller/usage?range=7d` | Daily spend series (`range` = `7d` / `30d`) |
| GET | `/api/v1/reseller/keys` | List your sub API Keys + per-key cost |
| GET | `/api/v1/reseller/keys/{id}` | Single key detail |
| POST | `/api/v1/reseller/keys` | Create a sub Key (**plaintext returned once**) |
| POST | `/api/v1/reseller/keys/{id}/enable` | Enable a key |
| POST | `/api/v1/reseller/keys/{id}/disable` | Disable a key |
| PATCH | `/api/v1/reseller/keys/{id}` | Update quota / concurrency |

---

## 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.

```bash
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:

```bash
# 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": "..."}`

| Status | Meaning |
|---|---|
| 401 | Invalid or missing token |
| 403 | Account not active (partner access not approved / suspended) |
| 404 | Key not found or not yours |
| 422 | Validation / quota error |
| 429 | Rate limited |

---

## 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](https://qcode.cc/partner-program)
- Questions? → in-site live chat, or email `hi@qcode.cc`.