Package invocation token setup guide

Use the hosted package details page when an external trusted client needs to call one Kody package export through the package invocation HTTP API. The create form lists Any export (*) plus each export from the package manifest. Setup query params prefill that selection. The agent may construct a prefilled setup URL, but the agent must never see, generate for chat, or place the raw bearer token in the URL.

For code that runs inside Kody, never use bearer tokens: statically import the target package (kody:@scope/package/export) when its name is known when the code is written, or call packages.invoke({ kodyId, exportName, params }) when the call must be dynamic. Package invocation tokens are for external systems such as webhooks, gateway proxies, CLIs, or other trusted personal clients that call Kody over HTTP.

When to use /account/packages/:packageId?newToken=1

Use it when:

• a non-Kody process must invoke one saved package export
• the user will store the raw bearer token in that external system
• export access should be scoped to specific exports on that package

Do not ask the user to paste bearer tokens into chat. Do not include a rawToken, token, bearer, or token hash query parameter.

Existing token values can be rotated from the package's token editor. That field is write-only and optional: leaving it blank keeps the current bearer value, while pasting a new raw token replaces the stored hash. The UI never shows the existing raw token or token hash.

Agents can inspect existing token record metadata with package_invocation_token_list (requires package_id), package_invocation_token_get, and package_get (includes tokens). These capabilities return record ids, names, the owning package, export scopes, timestamps, last-used metadata, and revocation status for the signed-in user's own records. They never return raw bearer token values or stored token hashes.

When the exact bearer value does not matter, the user can click Generate in the raw-token field. Kody generates a high-entropy browser-side token, fills the password field, and offers a Copy control so the user can paste it into the external service or secret store. After saving, Kody stores only the hash and will not show the raw value again.

URL format

This section is only for token setup. Setup URLs under /account/packages/:packageId?newToken=1 open the browser UI where the signed-in user creates a token for that package. They are not package invocation URLs and must not be used by external workers, webhooks, or CLIs as the HTTP API endpoint.

Provide the user a URL like:

https://<your-kody-origin>/account/packages/<packageId>?newToken=1&name=Webhook%20Dispatcher&exportNames=dispatch-event

Wildcard export setup for a highly trusted client of one package:

https://<your-kody-origin>/account/packages/<packageId>?newToken=1&name=Trusted%20External%20Client&exportNames=*

Query params

Repeat params or comma-separate values for list fields. The form also accepts common snake_case and kebab-case aliases so agents can construct URLs from API field names without extra translation.

Invocation URL format

External callers invoke package exports with the owner-scoped route:

POST https://kody.codes/@:username/api/package-invocations/:kodyId/:exportName

The @:username segment is required and must be the public username of the package owner. Do not use the stale unscoped form /api/package-invocations/:kodyId/:exportName.

Export names are normalized for token scope checks. The URL path usually omits the leading ./, so an export scoped as ./process-video is invoked with the path segment process-video.

Concrete YouTube WebSub Worker example:

curl -X POST \
	"https://kody.codes/@kentcdodds/api/package-invocations/youtube-livestream-vod-manager/process-video" \
	-H "Authorization: Bearer <raw-token>" \
	-H "Content-Type: application/json" \
	-d '{
		"idempotencyKey": "youtube:<video-id>",
		"source": "youtube-websub-proxy",
		"params": {
			"videoId": "<video-id>"
		}
	}'

Request JSON source is an optional caller label for logs. It does not gate authentication or determine idempotency. For Kent's YouTube Worker, callers typically send "source": "youtube-websub-proxy".

Prefer canonical URL metadata from package discovery over manual string construction. package_get and package entity search details include canonical external invocation metadata with the URL, path, route export name, normalized export name used for token scope checks, token setup URL, and source guidance for each callable export.

A token belongs to one package. Cross-package HTTP clients call one package (an orchestrator or discovery package) and use packages.invoke inside Kody, or they speak MCP.

Agent instructions

1. Identify the saved package and export the external system needs to call.
   • Use package_get so the setup URL includes the saved package id.
   • Use * only when the client should call every export on that package.
2. If debugging an existing setup, call package_invocation_token_list with that package_id, package_invocation_token_get, or read tokens from package_get first to confirm which token record exists and whether its export scopes match the external caller. Do not ask the user to read token metadata out of the browser UI unless the capability response is insufficient.
3. Generate an /account/packages/<packageId>?newToken=1 URL with name and export scope. Those query params prefill the create form: exportNames checks the matching export boxes, and * checks Any export.
4. Ask the user to open the URL, confirm the export selection, paste their locally generated raw token into the Raw token field, or click Generate and copy/deliver the generated value before creating the token.
   • For rotation, ask the user to open the package details page, select the token, and paste or generate the new raw token.
   • The external service or secret store must receive the exact raw value that was pasted/generated.
5. Instruct the external caller to send:
   • POST to the canonical owner-scoped invocation URL from package metadata, not to an /account/packages/... setup URL
   • Authorization: Bearer <raw-token>
   • optional JSON source as a caller label for logs; it does not gate auth
6. Never display, log, store in docs, or send raw token material through chat or query params.

Verification notes for agents

The package details page is a browser-session UI route. Fetching /account/packages/:packageId from MCP execute returns an HTML app shell, not the client-loaded token list, and /account/packages.json requires the signed-in browser session cookie. Agents should not treat missing token metadata in the HTML shell as proof that a token was not saved.

For external invocation smoke tests, check failures in this order:

1. owner_slug_required: the endpoint is missing the @:username owner slug. Use /@:username/api/package-invocations/:kodyId/:exportName; /api/package-invocations/... is not an invocation route.
2. not_found: verify the owner slug matches the package owner and the kody id names a package that user owns.
3. invalid_token or Invalid package invocation token: the request reached bearer-token authentication on a correctly shaped owner-scoped endpoint. Rotate the package invocation token or check that the external secret contains the exact active raw bearer value scoped to that package.

Package export names are checked only after bearer-token authentication succeeds. Request source is recorded when present and does not fail the call.

Related

• External package invocation API
• Packages