Underheard Research docs
Manual pagesAPI keys

API keys

An API key lets a tool act as you, in your workspace. One key opens both doors: the REST API and the MCP server. Any member of a workspace can make one.

Make a key

  1. Open Settings, then API (/settings/research?tab=api).
  2. Under Your keys, give the key a name that says which tool will hold it (for example "HubSpot sync" or "Claude desktop").
  3. Tick Can edit if the tool should change things: add people, prepare links, create or update studies over MCP. Leave it off for a tool that only reads.
  4. Press Create key and copy the key. It is shown once; the platform keeps only a hash.

A key looks like uh_research_ followed by 43 letters, digits, _ or -.

What a key can do

  • It acts as you: it can reach exactly the studies and settings you can, and nothing more.
  • It is bound to one workspace: the one you were in when you made it. Make another key for another workspace.
  • Its scope is read, or read and edit. A read key never writes; the server refuses with 403 and says so.
  • It stops working the moment you are no longer a member of the workspace, and whenever you revoke it. Membership is checked on every call.
  • You can hold up to 25 active keys. Each name is unique among your keys.

Use a key

Send it as a bearer token:

Authorization: Bearer uh_research_...

For the REST API, add that header to the request. For MCP, give it to the client as the server's bearer token (see MCP server).

A request with a key needs no session cookie and no Origin header. A request without a key, from the browser, uses your session as before.

Revoke a key

On the same Settings page, press Revoke next to the key. Anything using it stops working at once. Revoke a key you think has leaked, then make a new one.

Keep it safe

  • Treat a key like a password: keep it in your tool's secret store, never in a repository, a ticket or a chat.
  • Prefer a read key wherever edits are not needed.
  • Name keys per tool, so you can revoke one without touching the others.
  • Keys made by Underheard staff for a workspace carry the older prefix uh_research_mcp_ and keep working.