Child API Keys

Child keys (also called "standalone" keys) are additional API keys you can create from your Yukkai account, each with a fixed budget allocated from your Wallet balance at creation time. They're perfect for giving bounded, revocable access to something you don't fully trust with your full account.

What are Child Keys?

Child keys are:

• Separate API keys — each has its own yk_live_v1_... value.
• Budget-limited — you allocate a fixed amount from your Wallet when creating the key.
• Revocable — you can kill a child key at any time, and its unused budget is refunded to your Wallet.
• Independent — killing one child key never affects the master key or other child keys.

When to Use Child Keys

Use child keys for:

• Applications created with Yukkai — give your app a bounded budget instead of your master key.
• Scripts and automations — limit how much a script can spend.
• Team members or contractors — give someone access without sharing your master key.
• Test environments — isolate test usage from production.
• Any integration requiring a revocable, limited budget — maintain control over spend.

How to Create a Child Key

1. Go to Settings → API Keys.
2. Click Create Child Key (or Add Standalone Key).
3. Set a budget — the amount to allocate from your Wallet (e.g. $10, $50, $100).
4. Optionally give it a label (e.g. "Production API", "Test Script").
5. Click Create.
6. Save the key immediately — it's shown only once.

What Happens

• The allocated budget is deducted from your Wallet (a child-allocation transaction).
• A new yk_live_v1_... key is generated.
• The key is displayed once — save it immediately.
• The key can be used exactly like the master key (same proxy, same endpoints).

Important: Child Keys Are Not Recoverable

Unlike the master key, a child key's data is not recoverable if lost — its "partA" equivalent isn't retained the same recoverable way.

Save a newly created child key immediately. If you lose it:

• You cannot view it again.
• You cannot recover it.
• You must create a new one (and the old one's budget remains allocated until you kill it).

Using a Child Key in a Third-Party App

A child key is a standard yk_live_v1_... value — it authenticates against the Yukkai proxy exactly like the master key does. Any third-party app or script that needs AI can call it directly with a plain OpenAI-compatible HTTP request.

No Yukkai SDK, no session token, no extra headers beyond a bearer token.

Proxy URL

POST https://yukkai-proxy.yukkai-api.workers.dev/v1/chat/completions

Headers

Authorization: Bearer <the child key, yk_live_v1_...>
Content-Type: application/json

Request Body

{
  "model": "deepseek/deepseek-v4-flash",
  "messages": [
    { "role": "user", "content": "Hello!" }
  ],
  "stream": false
}

Model Parameter

The model parameter can be any real model id normally available on OpenRouter (e.g. anthropic/claude-opus-4, openai/gpt-5, deepseek/deepseek-v4-flash).

Not allowed: Yukkai meta-models like yukkai/fusion, yukkai/frontier, yukkai/free — those are Yukkai-app-internal routing, not meant for external calls.

Stream Parameter

• stream: false — returns a single JSON response (as shown above).
• stream: true — returns SSE chunks, the same way Yukkai's own client consumes them.

Example Response (Non-Streaming)

{
  "id": "gen-...",
  "choices": [
    {
      "message": { "role": "assistant", "content": "Hello! How can I help you today?" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 9, "completion_tokens": 10, "total_tokens": 19 }
}

How Budget Metering Works

Spend is metered against that specific child key's fixed budget only:

• It never touches the master key or the rest of the Wallet balance.
• It stops working once the budget is exhausted or the key is killed.
• Each child key has its own independent budget — one key's usage doesn't affect another's.

When the Budget Runs Out

When a child key's budget is exhausted:

• Requests using that key will fail with an HTTP 402 (Payment Required) error.
• The key remains valid (not automatically killed).
• You can either:
• Kill the key (and get a refund of any unused portion — but if it's exhausted, there's nothing to refund).
• Create a new child key with a fresh budget.

Killing a Child Key

You can kill a child key at any time:

1. Go to Settings → API Keys.
2. Find the child key in the list.
3. Click Kill (or Revoke).
4. Confirm the action.

What Happens

• The key is disabled immediately — it stops working right away.
• The unused budget is refunded to your Wallet (a child-refund transaction).
• The key cannot be re-enabled — killing is permanent.

Example

You create a child key with a $50 budget. After using $30, you kill the key:

• The key stops working immediately.
• $20 is refunded to your Wallet.
• You see a child-refund transaction for $20 in your Wallet history.

Child Keys vs. Master Key

	Master Key	Child Keys
Quantity	Exactly one per account	Any number
Budget	Unlimited (draws from Wallet)	Fixed budget allocated at creation
Recoverable if lost	✅ Yes (via iCloud Keychain)	❌ No (must create a new one)
Revocation	Regenerate (invalidates everywhere)	Kill individually
Refund on kill	N/A (can't kill master key)	✅ Unused budget refunded
Use case	Your main account access	Bounded, revocable access for integrations

Rotation and Revocation

Master Key

• Regenerate — issues a brand new master key; the old one is invalidated everywhere at once (all your devices, via iCloud Keychain sync).
• Blast radius — affects everything, all devices.
• Use case — if the master key may have leaked.

Child Keys

• Kill individually — each child key can be killed independently.
• Blast radius — affects only that one key.
• Use case — revoke access for a specific integration or team member.

There is no per-session or time-windowed key rotation — only these two explicit user-triggered actions.

Common Use Cases

Giving an App a Bounded Budget

You're building an app that uses Yukkai for AI. Instead of embedding your master key:

1. Create a child key with a $100 budget.
2. Embed the child key in your app.
3. Monitor usage in Settings → API Keys.
4. If the app goes rogue or the key leaks, kill it — you lose at most $100, not your whole Wallet.

Testing a New Integration

You want to test a script that calls the Yukkai proxy:

1. Create a child key with a $5 budget.
2. Use it in your test script.
3. If something goes wrong (infinite loop, bug), you lose at most $5.
4. Kill the key when done testing, and any unused portion is refunded.

Giving a Contractor Access

You hire a contractor to build an integration:

1. Create a child key with a $50 budget.
2. Give them the child key.
3. When the project is done, kill the key — they no longer have access, and unused funds are refunded.

Rules and Common Mistakes

✅ Do

• Save child keys immediately — they're shown only once.
• Use child keys for integrations — don't share your master key.
• Set appropriate budgets — allocate only what the integration needs.
• Kill keys when done — revoke access and get a refund.
• Label keys clearly — so you remember what each one is for.

❌ Don't

• Don't assume you can recover a lost child key — it's gone; create a new one.
• Don't assume a killed key's budget is lost — it's refunded to the Wallet, not forfeited.
• Don't confuse child keys with personal OpenRouter keys — the master/child system is Yukkai-account-only.
• Don't use Yukkai meta-models in external calls — use real model ids like deepseek/deepseek-v4-flash.

Examples

User asks how to create a child key

User: "How do I create an API key for my app?"

Yukkai: "Go to Settings → API Keys and click 'Create Child Key'. Set a budget (e.g. $50), give it a label like 'My App', and click Create. Save the key immediately — it's shown only once. The budget is deducted from your Wallet, and you can kill the key at any time to revoke access and get a refund of the unused portion."

User lost a child key

User: "I lost the child key I created. Can I see it again?"

Yukkai: "No — child keys are not recoverable if lost. You'll need to create a new one. The old key's budget remains allocated until you kill it, so go to Settings → API Keys, find the lost key in the list, and kill it to refund the unused budget to your Wallet."

User asks about budget limits

User: "What happens when a child key's budget runs out?"

Yukkai: "When a child key's budget is exhausted, requests using that key will fail with an HTTP 402 error. The key remains valid but won't work until you either kill it (and get no refund, since it's exhausted) or create a new child key with a fresh budget."

User wants to use Fusion in a third-party app

User: "Can I use Yukkai Fusion in my app via the API?"

Yukkai: "No — Yukkai meta-models like yukkai/fusion are internal to the Yukkai app and not available for external API calls. When using a child key in a third-party app, specify a real model id like deepseek/deepseek-v4-flash or anthropic/claude-opus-4."

Good to Know

• Child keys are perfect for integrations — bounded, revocable, independent.
• Save them immediately — they're shown only once and can't be recovered.
• Killing a key refunds unused budget — you don't lose money by revoking access.
• Each key has its own budget — one key's usage doesn't affect others.
• Use real model ids in external calls — not Yukkai meta-models.

Learn More

• Account Key — Understanding the master key and split-key design.
• Yukkai Wallet — How Wallet billing works.
• Recharging Credits — Topping up your Wallet.
• Error Codes — Understanding HTTP 402 and other errors.