---
title: The workspace key
description: "How to get your workspace key, sign in with it, rotate it, recover it when it is lost, and verify your domain to lift the limits."
theme: { accent: "#1f6feb", background: light }
translations: { de: de/hilfe-schluessel }
---

# The workspace key

A workspace belongs to a domain you control. Its key, which starts with
`fw_`, is the only credential: the web app, the API, MCP and the command-line
tool all take it.

## Get a key

In the web app, open app.frwrd.to, choose "Create a workspace" and enter
your domain, for example `acme.com`. Or call the API:

```
curl -X POST https://api.frwrd.to/v1/workspaces -H "Content-Type: application/json" -d '{"domain":"acme.com"}'
```

The answer holds the key and a DNS record to publish. **The key is shown
once.** frwrd.to stores only a hash of it and cannot show it again, so
save it right away. Creating workspaces is limited to 5 per minute per
address.

## Use it

- **Web app:** enter the key on the sign-in page. The browser keeps a session, never the key, for at most 30 days.
- **API:** send the header `Authorization: Bearer fw_...`.
- **MCP:** the same header, see the MCP help.
- **Command-line tool:** set `FRWRD_KEY` in the environment.

Never put the key in a URL, a link or a page: addresses end up in logs,
browser history and shared screenshots, and pages are public.

## Verify your domain

Until the domain is verified, a workspace holds at most 50 links and 3
pages, and it expires 31 days after you created it. Verifying lifts the
limits to 10,000 links and 50 pages, removes the expiry, and unlocks a
handle (`/@acme`), vanity link hashes and custom page domains.

To verify, publish a DNS TXT record at `_frwrd.acme.com` with the value
that creating the workspace returned. You can read it again at any time with
`GET /v1/workspace`. When the record is visible, press Verify in the web
app or call:

```
curl -X POST https://api.frwrd.to/v1/workspace/verify -H "Authorization: Bearer $FRWRD_KEY"
```

DNS can take a while to spread. If the record is not visible yet, the
answer says so and repeats it, and you can try again.

## Rotate the key

If a key may have leaked, issue a new one. The old key stops working at
once, and web sessions end:

```
curl -X POST https://api.frwrd.to/v1/workspace/rotate-key -H "Authorization: Bearer $FRWRD_KEY"
```

The new key is shown once, too.

## Lost the key

You recover a workspace by proving you control its domain, in two steps and
without a key.

1. `POST /v1/workspaces/recover` with `{"domain":"acme.com"}` returns a TXT record and a `recovery_secret`. Nothing changes yet, and the old key keeps working.
2. Publish the record at `_frwrd.acme.com`, then call `POST /v1/workspaces/recover/confirm` with the domain and the `recovery_secret`. The answer holds a new key, and the old one dies.

```
curl -X POST https://api.frwrd.to/v1/workspaces/recover -H "Content-Type: application/json" -d '{"domain":"acme.com"}'
curl -X POST https://api.frwrd.to/v1/workspaces/recover/confirm -H "Content-Type: application/json" -d '{"domain":"acme.com","recovery_secret":"..."}'
```

A workspace that was never verified loses its links when it is recovered,
because anyone could have created it. The command-line tool has both steps
too: `frwrd workspace recover acme.com`, then `frwrd workspace recover-confirm acme.com`.

- [Back to help](/@frwrd.to/help)