Docs · Share tokens

Share tokens — hand a client ONE install command

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, so "handoff" is one command, not an onboarding call.

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/bundles/{bundle_id}/share-tokens
x-api-key: ***
content-type: application/json

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

/api/cookbooks/* still works as a backward-compatible alias for every endpoint on this page — new integrations should use /api/bundles.

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.

The one command you actually send

This is what the client's agent runs — their x-api-key is the cbt_ token you minted, not your own key:

curl -sS https://app.loopskill.io/api/mcp/http/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: cbt_<8hex>_<32hex>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"loopskill_bundle_install","arguments":{}}}'

Empty arguments installs every active skill in the token's scoped bundle (bulk); the client's agent never sees a bundle ID or a bundle UUID — the token already carries the scope, per the MCP tool description in the live registry ("cbt_token callers may omit cookbook_id — it defaults to the token's scoped bundle"). The full initialize/session handshake this call needs is the same one every MCP call uses — see MCP setup.

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/bundles/* (or its /api/cookbooks/* alias) — 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 bundle 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/bundles/{bundle_id}/share-tokens/{token_id}/rotate

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

DELETE /api/bundles/{bundle_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.