API Keys
Create, view, re-issue, and revoke the instance keys that connect PodWarden Cores to Hub, and the personal access tokens AI clients use
What you see
URL: /dashboard/api-keys (requires login)
The API Keys page manages the two credentials Hub issues, and they are not interchangeable:
- Instance keys (
pwh_prefix) connect a PodWarden Core to Hub. One per Core, a machine credential -- this is the key you paste into PodWarden's Settings → Hub, and the key that authenticates catalog, DDNS, and support API requests. - Personal access tokens (
pwp_prefix) let an AI client act as you on one instance. You mint them while signed in, they are recorded against you, and they are what an MCP client sends to Hub as a Bearer token.
The page has a header with the title and a "Create Key" button, then a card listing your organization's instance keys, then a section for your personal access tokens. Empty states appear if you have none.
When you create a key or mint a token, a banner appears at the top showing the full value. This is the only time it is displayed -- copy it immediately.
The token list is yours, not the organization's: it shows the tokens you minted. Other members' tokens exist and are not shown here.
Fields / columns
Instance keys:
| Field | Description |
|---|---|
| Name | Descriptive label you chose when creating the key (e.g. "Production PodWarden") |
| Key prefix | First characters of the key (pwh_...) for identification |
| Last used | Date the key was last used to authenticate a request |
| Created | Date the key was created |
| Status | Current key status: active or revoked |
| Pin | pinned when the key's pin names an instance — whether you set it explicitly at mint or it imprinted on first hello — or binds on first use while it is armed but no Core has connected yet. Neither badge appears on an unpinned organization key |
Personal access tokens:
| Field | Description |
|---|---|
| Name | Label you chose when minting the token (e.g. "Claude Code on my laptop") |
| Key prefix | First characters of the token (pwp_...) |
| Instance | The one instance the token may reach. A token can never reach a second instance -- mint another token for that |
| Last used | Date the token last authenticated a request, or "Never used" |
| Expires | Expiry date, or "No expiry" |
| Status | active, expired, or revoked |
Creating an instance key
Create Key opens a modal with a name and two optional pinning controls:
| Field | Description |
|---|---|
| Key Name | Required. A descriptive name to identify this key |
| Pin to instance ID | Optional. A pinned key only accepts tunnel connections from that one instance |
| Pin on first use | Optional checkbox. The key imprints on the first Core that connects (trust-on-first-use) and refuses every other |
The two are mutually exclusive -- filling one disables the other. Pinning is asserted by the Core, not proven; it establishes that the same identity keeps coming back on the same key.
There is no re-pin and no un-pin. A key pinned to the wrong Core is revoked and replaced. After revoking, the next key is imprinted by whichever Core connects first, so shut down or disconnect the wrong Core before deploying the replacement key.
Minting a personal access token
New token opens a modal with three fields: a name, the instance the token may reach, and an expiry. Expiry choices are 30 days, 90 days, 1 year, or no expiry; 90 days is preselected. All three are required to mint except the expiry, which may be "No expiry".
The instance list is populated from the Cores connected to your organization. If it is empty, connect a Core first -- a token must be scoped to something.
Who can do what
| Action | Required |
|---|---|
| Create or revoke an instance key | admin or owner |
| Mint a personal access token | member (any organization member) |
| Revoke a personal access token | the token's minter, or an organization admin |
| Rotate a personal access token | the token's minter only -- not an admin, because rotation hands the caller a live secret attributed to another human |
Available actions
| Action | Where | What it does |
|---|---|---|
| Create Key | Page header button | Opens a modal to name, optionally pin, and create a new instance key |
| Copy | Created key banner | Copies the full key value to the clipboard |
| Dismiss | Created key banner | Hides the key display banner |
| Re-issue | Refresh icon per key row | Generates a new key value for the same key record. The old value stops working immediately. |
| Revoke | Trash icon per key row | Permanently deactivates the key. It cannot be re-activated. |
| New token | Personal access tokens section | Mint a token: name it, pick the instance it may reach, and choose an expiry |
| Revoke token | Trash icon per token row | Immediately invalidates the token. Any AI client using it stops working. |
This page has no rotation control. Rotation -- which mints a replacement and keeps both credentials valid for a grace window -- lives on MCP access, for both instance keys and personal access tokens.
Status badges
| Badge | Meaning |
|---|---|
| active | Credential is valid and can be used for authentication |
| expired | A token past its expiry. It authenticates nothing |
| revoked | Credential has been revoked and will be rejected on use |
| pinned | The instance key's pin names one Core, set explicitly at mint or imprinted on first hello |
| binds on first use | The instance key is armed and will imprint on the first Core that connects |
Related docs
- MCP access -- Connect an AI client, and rotate either credential
- Dashboard -- Overview showing API key count
- Settings: Hub -- Configure your PodWarden instance to use a Hub instance key
- Admin API Keys -- Admin view of all keys across organizations