Account Key (yk_...)

Your Yukkai account key (starting with yk_...) is the master key that authenticates you against the Yukkai proxy. It uses a split-key design where neither the client alone nor the server alone holds a usable OpenRouter key — the key is split into two components that must be combined to work.

What is the Account Key?

The account key is:

• Your identity — it identifies your Yukkai account.
• Your billing method — all usage under this key is billed to your Yukkai Wallet.
• Your access token — it authenticates requests to the Yukkai proxy.
• A split key — built so that neither the client nor the server alone can reconstruct the underlying OpenRouter key.

The Split-Key Design

The yk_... value stored in your Vault is the master key itself. It's built with a clever security design:

How It Works

1. The server holds a random component (partB / R).
2. The client holds partA = the real OpenRouter key XORed with that random component.
3. Neither half is usable alone:

• The client's partA is meaningless without the server's partB.
• The server cannot reconstruct the real key from partB alone.

1. When a request is made:

• The client sends partA to the Yukkai proxy.
• The proxy combines it with the server's partB.
• The combined result is the real OpenRouter key, which is used to service the request.
• The real key is never stored in one place.

Why This Design?

• Security — if either the client or the server is compromised, the attacker doesn't get a usable key.
• Revocability — the server can invalidate partB at any time, rendering all client copies useless.
• No single point of failure — the real key never exists in one location.

Key Format

The master key has this format:

yk_live_v1_...

• yk_ — Yukkai key prefix.
• live_ — production environment (vs test_ for development).
• v1_ — key version.
• ... — the split-key component (partA).

How the Master Key is Created

The master key is created automatically during onboarding:

1. You sign up for a Yukkai account.
2. The app calls YukkaiKeyService.ensureMasterKey().
3. If a master key already exists locally (in Keychain), it does nothing (idempotent).
4. Otherwise, it calls the backend (ykCreateMasterKey) to obtain one.
5. The key is stored in synchronizable iCloud Keychain (so it syncs across your devices automatically).
6. The key is registered with LLMKeyManager so it becomes selectable as an account.

iCloud Keychain Sync

Because the key is stored in synchronizable iCloud Keychain:

• It automatically syncs across all your devices signed into the same iCloud account.
• You don't need to manually copy the key between devices.
• If you regenerate the key on one device, the old key is invalidated everywhere at once.

Self-Healing

A self-healing call (ykSyncProjection) repairs the server-side routing projection if it ever gets out of sync. This runs automatically — it's not something you trigger manually.

Where the Key is Stored

The master key is stored in:

• macOS Keychain (via the Vault tool) — the secure enclave that stores passwords and certificates.
• Synchronizable iCloud Keychain — so it syncs across your devices.

The key is never:

• Sent to Yukkai's servers in plain text.
• Logged or displayed in plain text.
• Accessible to other apps.

Regenerating the Master Key

If your master key may have leaked, you can regenerate it:

1. Go to Settings → API Keys.
2. Find your master key.
3. Click Regenerate.
4. Confirm the action.

What Happens

• A brand new key is issued.
• The old key is invalidated everywhere at once (all your devices, via the same iCloud Keychain sync).
• You'll need to re-authenticate on all devices.

When to Regenerate

Regenerate the master key if:

• You suspect it has been compromised.
• You shared it accidentally (e.g. in a screenshot, log file, or public repo).
• You want to rotate keys as a security best practice.

Note: Regenerating the master key does not affect child keys — they remain valid.

Using the Master Key

The master key is used automatically when you:

• Select Yukkai Fusion, Yukkai Frontier, or Yukkai Free from the model picker.
• Use media generation (image, video, music).
• Access any Yukkai-billed service.

You don't need to manually provide the key — it's handled transparently by the app.

Master Key vs. Child Keys

The master key is the root key for your account. You can also create child keys (also called "standalone" keys) with fixed budgets allocated from your Wallet.

	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
Use case	Your main account access	Bounded, revocable access for integrations

See Child API Keys for details.

Master Key vs. Personal OpenRouter Key

	Yukkai Master Key (yk_...)	Personal OpenRouter Key (sk-or-...)
Split-key design	✅ Yes	❌ No (standard API key)
Billing	Yukkai Wallet	OpenRouter account
Meta-models	✅ Fusion, Frontier, Free	❌ Not available
Child keys	✅ Supported	❌ Not supported
Stored in	iCloud Keychain	macOS Keychain
Syncs across devices	✅ Yes (via iCloud)	❌ No (manual copy)

Security Considerations

What the Split-Key Design Protects Against

• Client compromise — if your Mac is compromised, the attacker only gets partA, which is useless without the server's partB.
• Server compromise — if Yukkai's server is compromised, the attacker only gets partB, which is useless without the client's partA.
• Man-in-the-middle — even if someone intercepts partA in transit, they can't use it without partB.

What It Doesn't Protect Against

• Both client and server compromised — if an attacker has access to both halves, they can reconstruct the key.
• Your iCloud account — if someone gains access to your iCloud account, they can access the key via iCloud Keychain sync.

Best Practices

• Don't share your master key — treat it like a password.
• Regenerate if compromised — if you suspect the key has leaked, regenerate it immediately.
• Use child keys for integrations — don't give your master key to third-party apps or scripts; create a child key with a fixed budget instead.

Examples

User asks about the key format

User: "What does my Yukkai API key look like?"

Yukkai: "Your Yukkai master key starts with yk_live_v1_.... It's a split-key design where the client and server each hold a component, and neither half is usable alone. The key is stored securely in your iCloud Keychain and syncs across your devices."

User wants to see their key

User: "Can I see my master key?"

Yukkai: "Your master key is stored in the macOS Keychain and isn't displayed in the app for security reasons. If you need to use it in a third-party app, you should create a child key with a fixed budget instead — that's safer than sharing your master key."

User suspects the key leaked

User: "I think I accidentally posted my API key in a public repo. What do I do?"

Yukkai: "Regenerate your master key immediately. Go to Settings → API Keys, find your master key, and click 'Regenerate'. This will issue a new key and invalidate the old one everywhere at once, across all your devices."

User asks about syncing

User: "Do I need to copy my API key to my other Mac?"

Yukkai: "No — your master key is stored in synchronizable iCloud Keychain, so it automatically syncs across all your devices signed into the same iCloud account. You don't need to manually copy it."

Good to Know

• The master key is split-key by design — neither client nor server alone can use it.
• It syncs via iCloud Keychain — no manual copying between devices.
• Regenerating invalidates the old key everywhere — use this if the key may have leaked.
• Child keys are separate — regenerating the master key doesn't affect child keys.
• Use child keys for third-party apps — don't share your master key.

Learn More

• Child API Keys — Creating bounded sub-keys for integrations.
• Yukkai Wallet — How billing works under the master key.
• Recharging Credits — Topping up your Wallet.
• Personal OpenRouter Key — Alternative to the Yukkai account system.