API Keys: Generate, Use, and Revoke

An API key is how everything outside a browser session talks to HTMLvault. A Custom GPT action, a Zapier step, a Clay enrichment table, a nightly CI job that publishes the ops dashboard — none of them can click a magic link in an inbox, so none of them can sign in the way a person does. They need a static credential: an hv_ key you generate once, paste into the integration, and revoke when it has outlived its purpose.

Liz Lemmon's weekly revenue report is the ordinary version of this problem — the numbers are ready at 6 a.m., she is not, and the job that publishes the link needs to authenticate without her.

This guide covers generating a personal key on /settings/api-keys, what the dashboard stores versus what it shows you, how to authenticate REST calls, how to revoke cleanly, and how Enterprise org keys sit above personal ones.

What an API key is for (and when you don't need one)

HTMLvault has no email-and-password login by design — accounts use magic links and passkeys. That is good for humans and useless for machines. API keys fill the gap: a long-lived bearer token that identifies your account to the REST API.

Keys are a Pro-and-up feature. On Free, /settings/api-keys shows a single gate card instead of the generator, with the honest reason: static keys unlock the REST API and the key-based integrations that cannot sign in — Custom GPT Actions, Gemini Gems, Grok, Cursor, and CI pipelines.

The exception worth knowing before you generate anything: MCP needs no key. If you are connecting Claude through the HTMLvault MCP server, the one-click connectors handle authentication themselves. Generate a key for MCP only if you are wiring up a client that asks for one; keys created from the MCP page come back tagged so you can tell them apart later.

Who this is for

• RevOps and ops — scheduled jobs that publish dashboards, lead lists, or reports as tracked links.
• Marketing — campaign pages generated by an automation platform instead of by hand.
• Sales engineering — a Custom GPT or agent that turns a call transcript into a proposal link.
• IT and security — the people who want each integration holding its own revocable credential rather than a shared one nobody owns.

Generating your first HTML sharing API key

The whole flow lives on one settings page.

1. Open Settings → API Keys (/settings/api-keys).
2. In the create row, type a name in the Key name (e.g. Zapier, CI pipeline) field. The Generate button stays disabled until the field has content.
3. Press Generate. It reads Generating… for a moment, then a one-time reveal box appears with the full key in monospace and a Copy button.
4. Copy the key into the integration's credential field before you navigate away. The helper text is not being dramatic: Copy this key — it won't be shown again.

Name keys after where they live, not after yourself. "Zapier" and "CI pipeline" tell a future reader which integration breaks if the key is revoked; "liz-key-2" tells them nothing. One key per integration is the rule that makes revocation survivable.

What the dashboard stores, and what it shows

Every key starts with the hv_ prefix, so it is recognizable in a config file, a log line, or a secret scanner's ruleset. After the one-time reveal, the full value is gone from the interface. The list row keeps only what you need to identify and manage it:

• The name you gave it, in bold.
• An MCP chip if the key was generated from the MCP page for a specific integration.
• A monospace metadata line: the truncated prefix, the created date, and either Last used with a date or Never used.
• A Revoke button on active rows, and a red Revoked badge plus a revoked date on inactive ones.

An Active / Revoked tab bar appears once you have at least one key, with counts on each tab. Empty tabs say so plainly — No active keys. or No revoked keys.

There is no show-key toggle, no rename, no per-key scope picker, and no usage chart. That is deliberate. A key you cannot re-read is a key that cannot be quietly copied out of the dashboard six months later, and the Last used date answers the only question anyone actually asks about an unfamiliar key: is anything still calling with this?

Authenticating REST calls

Send the key as a bearer token in the Authorization header. Creating a link is a POST with your HTML in the body:

curl -X POST https://htmlvault.com/api/v1/links \
  -H "Authorization: Bearer hv_9f2c81a4e7b60d35c1aa47f9" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly Revenue Dashboard",
    "html": "<html>…</html>",
    "expires_in": "7d",
    "password": "quarter-close"
  }'

The response returns the link URL and its id. Store the id — you will want it for the analytics call later:

curl https://htmlvault.com/api/v1/links/lnk_7d4a2f/analytics \
  -H "Authorization: Bearer hv_9f2c81a4e7b60d35c1aa47f9"

A few practical notes. Keep the key server-side: anything in front-end JavaScript is public, and a key in a shared HTML artifact is exactly the failure the secret scanner exists to catch. Read the key from an environment variable or your platform's secret store, never from a file you might paste into a chat window. And expect a 401 if the key has been revoked — treat that as a signal to check the dashboard, not to generate a replacement reflexively.

Worked example: the 6 a.m. dashboard job

A RevOps team wants Monday's revenue dashboard waiting in the leadership channel before the standup. The shape of it:

1. Generate a key named CI pipeline and store it in the scheduler's secret manager as HTMLVAULT_API_KEY.
2. The job builds the dashboard HTML from the warehouse, then POSTs it with expires_in: "7d" so last week's numbers cannot resurface in a forwarded thread.
3. It posts the returned URL to the channel.
4. Friday, a second call hits the analytics endpoint for that link id and writes views, unique visitors, and time-on-page back to a sheet — so you know whether leadership actually opened it. (Per-link analytics covers what each metric means.)

One key, one job, one purpose. If the scheduler is decommissioned, you revoke one credential and nothing else in the account notices.

Revoking a key

Revocation is immediate and permanent. Press Revoke on the row and confirm the prompt: Revoke this API key? Any integrations using it will stop working. The row moves to the Revoked tab with a red badge and a revoked date, and every request carrying that key starts failing.

Revoke on a schedule, not just in a crisis: when someone changes roles, when an integration is retired, when a key shows Never used months after creation, or the moment a credential might have been pasted somewhere it shouldn't. Because keys cannot be renamed or rotated in place, rotation is a two-step move — generate the new key, update the integration, confirm it works, then revoke the old one. Do it in that order and there is no outage window.

Revoked rows stay visible on purpose. "This key existed, was last used on the 12th, and was revoked on the 14th" is the kind of record that belongs in a security review. Pair it with the audit trail on Teams for the full picture of who did what.

Org keys: the Enterprise hierarchy

Personal keys belong to a person. That is correct for a rep's Custom GPT and wrong for a system integration that has to outlive whoever set it up — the classic failure is the billing sync that dies three weeks after an engineer's offboarding, for reasons nobody can reconstruct.

Enterprise org admins get a second card below the personal one: Org API Keys — shared credentials for system integrations, visible to all org admins. The mechanics are identical (name input, Generate, one-time reveal, Active/Revoked tabs), with two differences in the list rows: a grey ORG chip leads the name, and the metadata line adds By the admin who created it. Revoking one prompts its own confirmation: Revoke this org key? Any integrations using it will stop working.

Limits and caveats

• Keys are shown once. Lost the value? Generate a new key and revoke the old one. There is no recovery path, by design.
• No per-key scopes. A key carries your account's permissions. Segment by generating separate keys per integration, and revoke narrowly rather than granting narrowly.
• Free has no keys. The gate card points at Pro. MCP connectors remain the no-key path for Claude.
• Revocation is not reversible. Read the confirmation prompt — it names the actual consequence.
• Rate limits apply per account. Batch work belongs in create_links-style bulk calls rather than a loop of single requests.
• A key does not exempt content from policy. Links created over the API inherit your plan's expiry and retention settings and pass through the same regex PII and secret scan as anything created in the browser — nine categories, zero token cost. Sharing controls apply identically.

The point of an HTML sharing API key is that the automation is a first-class citizen with a name, a creation date, and an off switch. The RevOps lead gets a dashboard that publishes itself before the standup. The marketer gets campaign pages generated by the same tool that writes them. And IT gets what it never gets from a shared credential in a wiki: a list of exactly which integrations hold access, when each last used it, and a one-click way to end that access without breaking anything else.