---
title: Connector keys
description: What a ggui_user_* connector key is, the three ways to mint one, how per-app scoping and revocation work, and why it is not the same thing as a marketplace publisher key.
---

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](/hosted/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](/clients/claude-desktop/) 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:

```bash
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`](/cli/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:

```bash
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).

:::note[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`](/cli/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](/hosted/marketplace/).