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