Docs · Share tokens

Share tokens

You built a bundle for a client. Now you need to hand it to their agent — without handing over your own API key, your whole catalog, or a support ticket every time they lose it. A share token is a second, disposable key that reaches exactly one bundle and nothing else.

Why this exists

Your rec_live_ API key can read your entire account: every private bundle, every key, your billing state. Pasting that into a client's agent config means trusting them (and their infrastructure) with all of it forever.

A share token — prefix cbt_ — is scoped to one bundle at mint time. Give it to a client, a contractor, or another agent, and the worst case if it leaks is: they can act on that one bundle. Not your account.

Minting a token

From /library, open the Client delivery tab, find the bundle, pick a scope, and click Mint key. The token is shown once — copy it before you close the dialog.

POST /api/cookbooks/{cookbook_id}/share-tokens
x-api-key: rec_live_your_key
content-type: application/json

{"name": "handoff-install", "scope": "install"}

The three scopes

Every share token carries exactly one scope, chosen at mint time. Default is install — the token can read the bundle and pull skills, which is what a client handoff needs.

edit gives owner-equivalent access to that one bundle (add/remove skills) — it does not let the holder mint further share tokens. That guard is hard-coded: a share token can never create another share token.

What a share token cannot reach

These restrictions are enforced in middleware, before your bundle's authorization logic even runs — no scope, however permissive, overrides them:

• ✕ Any route outside /api/cookbooks/* — your skill catalog, other bundles, account, billing — is rejected outright.
• ✕ Any path containing /_publish returns 403 — regardless of scope. A share token can never publish a skill.
• ✕ A different bundle's ID in the URL — the token is bound to one cookbook at mint time, so a request for another bundle returns 403 token scope mismatch.

Rotation and revocation

Rotate a token to invalidate the old value and issue a new one under the same record — useful if you suspect a leak but still want the client connected:

POST /api/cookbooks/{cookbook_id}/share-tokens/{token_id}/rotate

Revoke a token entirely from /library → Client delivery, or directly:

DELETE /api/cookbooks/{cookbook_id}/share-tokens/{token_id}

Revocation is a soft-delete and takes effect immediately — the recipient's very next request gets 401 Invalid or revoked share token. There is no grace period.

Worked example: handing off a bundle

1. 1 Build the bundle in /library — add the skills the client needs, pin versions.
2. 2 Open the Client delivery tab, leave scope on install (the default), and click Mint key. Copy the cbt_<8hex>_<32hex> token shown.
3. 3 Send the client the one-line meta-skill install command with that token as their x-api-key. Their agent can now pull exactly this bundle's skills, on its own schedule — you never touch their machine.
4. 4 Engagement ends, or the token leaks? Revoke it from the same tab. Everything else in your account — other clients, your own keys — was never reachable from it in the first place.