Connector keys

A connector key is the bearer token that authenticates something — your agent, or an MCP host acting on your behalf — to hosted ggui at mcp.ggui.ai. Keys are prefixed ggui_user_ and travel as an ordinary HTTP header:

Authorization: Bearer ggui_user_…

That is the whole authentication story for the data plane. No client SDK, no session cookie, no signing step.

Minting a key

Three paths mint the same kind of row, and all three land in the same list in the ggui console.

From the console

Open Connector keys (/keys/connector), optionally type a label (Claude Desktop — laptop), and click Generate connector key. The secret reveals exactly once — copy it before you dismiss the dialog. There is no recovery: lose it and you mint a new one.

From an MCP host, through OAuth

When Claude Desktop or another MCP-Apps-aware client connects to mcp.ggui.ai, the OAuth ceremony sends your browser to the console’s consent screen. Approve mints a fresh key and hands it back to the client — you never see or paste it. The default label is built from the requesting client and the date:

MCP — <short client id> — <date>

When the host asked for a specific app (an RFC 8707 resource indicator naming one of your apps), the app’s display name is folded into the same template:

MCP — <appName> — <short client id> — <date>

The consent screen carries an optional Key name field that overrides the default before you approve. Cancel mints nothing — the client is redirected back with error=access_denied and the MCP server is never contacted.

From the CLI

Sign the CLI in once with the device flow, then mint from your terminal:

ggui login
ggui keys create --name "my agent runtime"

The secret prints exactly once, GitHub-PAT style. Pass --expires-at <iso8601> to give the key a hard expiry. See ggui login for the full device-flow walkthrough and the --keys-file variant that needs no account at all.

Account-wide and per-app keys

/keys/connector mints account-wide keys — they resolve to your default app when a session binds.

An app’s own Keys tab (/apps/[appId]/keys) mints keys bound to that appId, so a session opened with one is locked to that app. The programmatic endpoint for a per-app key carries the app in the path:

https://mcp.ggui.ai/apps/<appId>

OAuth flows that carried a per-app resource indicator bind the appId onto the minted row the same way.

Listing and revoking

The console’s key list shows one row per key: the ggui_user_ prefix, the label, created and last-used dates, and status (active or revoked). It is read-only today — revocation is a CLI operation:

ggui keys list
ggui keys revoke <id>

Revoke is a soft delete. The row stays for audit, and every subsequent request presenting that key returns 401 Unauthorized. There is no undo; generate a replacement and reconnect whatever you still want connected.

Revocation is per key, not per host. Every host holding that key loses access at the same moment — which is the argument for issuing one key per host, so you can cut off one without disturbing the rest.

Deleting an app revokes that app’s per-app keys as part of the cascade (the rows are kept for audit).

The key list is the connection list

Every path — console, OAuth, CLI — produces a row in the same table, so that table is the authoritative list of everything that can talk to ggui as you. The console’s Connected apps screen is a placeholder; there is no second registry to reconcile against.

Connector keys are not publisher keys

Two different key systems live under the ggui keys command. They share a noun and nothing else.

	Connector key	Publisher key
Shape	ggui_user_… bearer secret	Ed25519 keypair on disk
Purpose	Authenticate to mcp.ggui.ai	Sign marketplace artifacts
Created by	Console, OAuth consent, ggui keys create	ggui gadget publish / ggui blueprint publish, on first run
Registered by	Nothing — it works immediately	ggui keys register

If you are wiring an agent or an MCP host, you want a connector key. Publisher keys only matter when you publish to the marketplace.