# Getting an API key
An API key lets the [REST API](/docs/api/), the [CLI](/docs/cli/), and the [MCP server](/docs/mcp/) act on your behalf. Keys are available on the Starter plan and above.
:::caution[API access needs a paid plan]
The Free plan can't create API keys. The API, and the CLI and MCP server that use it, are available from the Starter plan up. On Free, the API Keys page shows an upgrade prompt.
:::
## Creating a key
1. In the dashboard, go to **Developers → API Keys** and click **Create API Key**.
2. Enter a **Name**, such as "Production CI/CD", and choose an **Expiration**: **Never expires** (the default), 30 days, 90 days, or 1 year. Click **Create Key**.
3. Copy the key from the **API Key Created** dialog. It's shown only once.
Creating a key needs a role that can edit monitors: Owner, Admin, or Manager. A Viewer sees "Creating API keys requires edit permission — your role is read-only."
## What a key can do
A key acts as the person who created it: every request is checked against that person's [role](/docs/team/#roles), so a Viewer's key can read but not change anything. Keys can't be limited any further yet. As the Create API Key dialog says, "Keys have full account access; scoped permissions are not yet available."
## Kinds of key
| | Workspace key | Account-wide key |
| --- | --- | --- |
| Created by | The dashboard, `POST /keys`, or `thq keys create` | Signing in with `thq login` |
| Belongs to | The workspace it was created in | Your account |
| Can reach | That workspace's projects only. Requests for another workspace's projects are refused. | Every project you can open. Each request uses the plan of that project's workspace. |
| On the API Keys page | In that workspace | In every workspace you open, with an **Account-wide** badge. You can revoke it from any of them. |
Keys created in the dashboard start with `thk_`. Keys created with `POST /keys`, `thq keys create`, or `thq login` start with `uk`. Either way, the whole string is the secret.
Account-wide keys are named "CLI · <computer name> · <date>" and never expire. `thq login` works only if the workspace you approve it from is on a paid plan.
:::caution[Creating keys over the API needs a workspace key]
`POST /keys`, and so `thq keys create`, refuses an account-wide key with `403` "API access isn't included on this workspace's plan. Upgrade to create API keys." Right after `thq login`, `thq keys create` fails even on a paid plan. To create keys from the CLI, set a dashboard key in `THQ_API_KEY`.
:::
## Using a key
| Tool | Where the key goes |
| --- | --- |
| REST API | The `X-API-Key` header, or `Authorization: Bearer `. See [Authentication](/docs/api/#authentication). |
| CLI | `thq login` saves one for you. For CI, set `THQ_API_KEY`. |
| MCP server | The `TUNNELHQ_API_KEY` environment variable in your client's config. |
## Seeing usage
At the top of the **API Keys** page, you'll see the workspace's API usage against your plan's limits: today, per minute, and this month, a daily chart, and requests by endpoint. It covers every key in the workspace.
Below it, the page lists each key's **Name**, a **Key** preview, **Status** (**Active**, **Disabled**, or **Expired**), **Last used**, **Created**, and **Expires**.
To see one key's usage, open its actions menu (**⋯**) and choose **View details**, or click the key's name. The key's page shows its requests today and over the last 7 and 30 days, a daily usage chart, and a breakdown by endpoint.
## Disabling and revoking a key
| To | In the dashboard | With the API or CLI |
| --- | --- | --- |
| Stop a key until you turn it back on | **⋯ → Disable**, and later **Enable** | `DELETE /keys/:id` or `thq keys revoke ` |
| Delete a key for good | **⋯ → Revoke**, then **Revoke Key** | `DELETE /keys/:id?hard=1` or `thq keys revoke --hard` |
A key disabled through the API or CLI shows as **Disabled** and can be enabled again in the dashboard. Revoking can't be undone, and anything using the key loses access immediately. An expired key gets `401` "API key has expired".
### Keys in this workspace
Owners and Admins also see a **Keys in this workspace** section. It lists every key created in the workspace, whoever made it, and they can revoke any of them. All of these keys count against the workspace's plan. Revoking one stops it working immediately, but doesn't remove its owner from the workspace.
## Keeping keys safe
- Store keys in an environment variable or a secret manager, never in source control.
- Set an expiration on keys you only need for a while.
- If a key leaks, revoke it and create a new one.
- For AI assistants, consider a [read-only MCP setup](/docs/mcp/#safer-setups).
## Still stuck?
Email [support@tunnelhq.com](mailto:support@tunnelhq.com).