the workspace key
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.
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 and enter your domain under "Create a workspace", for example acme.com. The next page has one job: save your key. Copy it, or download it as a file, then continue to your workspace. 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 under "Sign in with your key". 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_KEYin 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.
Verifying is optional until the workspace expires. In the web app, the dashboard shows a banner until the domain is verified (you can dismiss it for a week); its "Prove your domain" button, or the same link on the Settings page, opens a page with the record's name and value, each with a Copy button, the steps, and a "Check now" button. To do it by hand, 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 "Check now" 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. Rotating also removes the recovery e-mail, because whoever had the old key could have set it: set yours again.
Lost the key
You recover a workspace by proving you control its domain, in two steps and without a key.
POST /v1/workspaces/recoverwith{"domain":"acme.com"}returns a TXT record and arecovery_secret. Nothing changes yet, and the old key keeps working.- Publish the record at
_frwrd.acme.com, then callPOST /v1/workspaces/recover/confirmwith the domain and therecovery_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.
Without a proven domain: the recovery e-mail
Set a recovery e-mail first, while you still have the key: in the web app under Settings, Account, "Recovery e-mail", or frwrd workspace recovery-email you@example.com (MCP set_recovery_email, API PUT /v1/workspace/recovery-email). We mail a code; entering it confirms the address. Only a fingerprint of the address is stored, never the address.
Lost the key: on the sign-in page, "Lost your key?", type the address and enter the code from the mail. You are signed in and get a new key, once; the old one stops working. The same from the shell: frwrd workspace recover-email you@example.com, then frwrd workspace recover-email-confirm you@example.com with the code in FRWRD_RECOVERY_CODE. A workspace with a proven domain recovers with the domain instead.
Delete your workspace
You can delete a workspace yourself: in the web app (the "Delete workspace" section at the bottom of Settings leads to a confirmation page where you type the domain), with frwrd workspace delete --confirm acme.com, over MCP with delete_workspace, or with the API:
curl -X DELETE https://api.frwrd.to/v1/workspace -H "Authorization: Bearer $FRWRD_KEY" -H "Content-Type: application/json" -d '{"confirm":"acme.com"}'
Deleting a workspace stops its key and takes its pages offline at once; after 7 days the pages and settings are deleted. Short links keep working. Proving the domain (key recovery, above) within 7 days restores everything; up to 60 days, the links. After 60 days the domain is free and the links keep working without an owner. Browsers may keep cached copies of a page, its QR code and images for up to an hour after the delete.
At once, the key stops working, you are signed out of the web app, and every address of your pages answers "not found", also on your own domain. Your short links and printed QR codes keep redirecting and counting clicks, the links your pages made included. After 7 days the pages, their versions, your custom domains, the UTM defaults and the default language are deleted, and the handle stays reserved, so nobody else can take it. For 60 days the domain stays with the workspace: to use it again, recover the key. After that it is free to register as a new, empty workspace; your old short links keep redirecting, with no owner. Backups keep the data for up to 35 days and are used only to restore the service after a failure.
