Console · Migration Tool
Get the key for each site
Last updated 18 November 2026
Get the key for each site
A migration needs a key for each site: one for the new Insites site it copies to, and one for the old site it copies from. The tool reads and writes through each site's admin API, which is the only way to copy rows with their original ids and dates.
| Site | The key | Where it goes in the tool |
|---|---|---|
| The new Insites site (the destination) | A Console access token, from its CLI tab. A GraphQL admin key works too. | Destination, Connect |
| The old previous-platform site (the source) | Its GraphQL admin key, or your previous Insites Console email and password with the site UUID. | Source, Connect |
The new Insites site: an access token from Console
- Sign in to Insites Console and open the new site.
- Open the CLI tab. The Access Token card is the last one on the tab. Press Get my token.
- Copy the token. It starts
iak_. - In the tool, type the new site's address into Insites site URL and paste the token into Console access token. The tool works out which site the token opens from the address. Use the site's own address, as Insites Console shows it, ending
prod01-insites.ioorstaging-insites.io. Not the site's public domain: until the cutover, it still opens the old site.
You need the Developer role on the site. A migration changes code, settings and files as well as records, and an Editor's token can only change records. The tool checks the role when you connect and says so before anything is planned. If you are an Editor, ask an admin of the site to give you the Developer role in Console, then get a new token.
When you connect, the tool also checks that the token is for the site at the address you typed. A token copied from a different site is refused. If the new site does not accept what was pasted in Console access token, the message says so. A common cause is a browser that fills in saved passwords: clear the field and paste the token again. The tool asks browsers and password managers not to fill in its key fields, but some still do. Pasting the whole command Console shows under the token (Copy command, which starts insites-cli env add) works too.
A GraphQL admin key from the Insites CLI works for the new site too, pasted into the same field. The access token is the better choice: it needs no CLI, and every change is recorded against your name.
What the token does
- It is yours alone. Everything the tool changes with it is recorded in Console against your name.
- It lasts 90 days. Getting a new token replaces the old one, so do not take a new one while a migration is loading.
- When the migration is finished, you can revoke it on the same Access Token card.
- Access tokens exist only for sites on the Insites private stack, at addresses ending
prod01-insites.ioorstaging-insites.io. Every new Insites site is one.
The old previous-platform Insites site
A previous-platform site has no access token. There are two ways to connect it: its GraphQL admin key, or your previous Insites Console sign-in. Use one, not both: if you fill in both, the tool asks you to clear one. Connect the live (production) site, not a UAT or staging copy, because the final sync copies the changes made on it.
An Insites v4 site. Choose Insites v4 as the source. It connects the same two ways, through the previous Insites Console, with one difference: a v4 site has no /admin/api page, so find its UUID in the previous Insites Console, on the site's details. Insites v4.
The previous Console, not the Insites one. console.insites.io now opens the Insites Console, which is where you get the new site's access token. A previous-platform site is still reached through the previous Insites Console, so both ways below use your previous Insites Console sign-in: the email and password you used for the old site. The tool knows where the previous Console is, so you only give your sign-in.
Way 1: the GraphQL admin key, from the Insites CLI
- Install the CLI, or update it if you have an older one:
npm install -g @insites/insites-cli. CLI 6.3.1 or later signs in to the previous Insites Console. An older version triesconsole.insites.io, which no longer signs in a previous-platform site. - Find the site's UUID. Open
https://your-instance/admin/api: it is in the Site Details table. - In an empty folder, run:Enter your previous Insites Console password when it asks.
insites-cli env add old-site --email [email protected] --instance-uuid THE-UUID - Open the
.insitesfile the command wrote in that folder. The admin key is the value ofkeyunderold-site. - Paste it into the GraphQL admin key field in the tool, then delete the folder: the tool does not need the file again.
The CLI signs you in with your previous Insites Console password. If your previous Console account uses single sign-on and has no password, the CLI cannot sign you in, and Way 2 cannot either: ask Insites support for the site's GraphQL admin key, and paste that.
Way 2: your previous Insites Console sign-in, without the CLI
Leave the GraphQL admin key empty and fill in all three of these instead:
- Site UUID: in the previous Insites Console, or the Site Details table at
https://your-instance/admin/api. - previous Insites Console email: the email you sign in to the previous Insites Console with.
- previous Insites Console password: your previous Insites Console password. Not your Insites Console sign-in.
When you connect, the tool signs in to the previous Insites Console once for you, the way the CLI does, and gets the site's GraphQL admin key. It keeps that key like any other, below, and does not keep your email or password: they are used for that one sign-in and then dropped. If one of the three is missing, or the previous Console does not accept them, the tool says so before anything is kept.
Connected with a password before release 0.5.0? Before release 0.5.0 the tool kept a previous Console password and signed in with it each time. It no longer does. A source connected that way says it was connected before the tool stopped keeping passwords and cannot be opened. Connect it again: paste the GraphQL admin key, or give your previous Insites Console email and password once. Nothing the migration has done is lost.
Not the REST API key. The key you see under Integrations in a site's admin starts with instance_. It cannot keep ids or created dates, so the tool refuses it.
You set up reCAPTCHA again on Insites
The admin key reads everything the tool copies, but not an integration's own keys. reCAPTCHA is the one most sites have: the old site's secret key cannot be read through its admin API, the new site's reCAPTCHA keys cannot be written through it, and the new address has to be added to the key in Google's reCAPTCHA admin console. So the tool cannot copy it. hCaptcha needs nothing: the new site draws it with its own key.
Expected on every migration of a site whose forms use reCAPTCHA. Until it is set up, each of those forms shows and logs “can't find configuration for CAPTCHA” on the new site, and Verify lists it under Worth a look, marked In a To do job. It is not a fault in the migration, so LOGS accepts it, with that reason, until the job is ticked. The To do list under Before cutover, in Launch, carries the job as Set up the spam check (reCAPTCHA) on the new site's forms.
Set it up before cutover:
- The job names each form or page that checks reCAPTCHA, with the page it is on and its file.
- Get the site key and secret key in the Google reCAPTCHA admin console: the key the old site uses, of the same version. Add the new site's address, and the site's own domain if it has one, to the key's domains. Google refuses a form sent from a domain the key does not list.
- Ask Insites support ([email protected]) to set reCAPTCHA up on the new site with that site key and secret key, and ask how to send the secret key safely. A Insites site takes reCAPTCHA keys from Insites: Insites Console has no screen for it yet, and the admin's Integrations, reCAPTCHA page keeps keys this check does not read. We measured this on a test site on October 24, 2026.
- Or, with no keys at all, switch each one to the platform's hCaptcha, which the new site provides with its own key: change the spam_protection tag to
spam_protection “hcaptcha”. A form whose spam protection setting names reCAPTCHA must name hCaptcha too, or its submissions may be refused. - Submit a form on the new site and check it goes through, then press Check again.
What happens to the key
It goes from the field straight to the tool over HTTPS, is encrypted with the tool's own key, and is never shown again. It is never kept in your browser.
- Kept for as long as the migration needs it. Once a migration holds the key, the tool keeps it until you close the migration, or until the migration has gone unused for 90 days. It does not run out on a date, whatever the run's status: a verified, stopped, failed or rolled back migration keeps its keys, so a check, a nightly sync, the watch or a rollback later on works without asking again. Keeping a key is recorded in its audit log with the run it was for.
- A key no migration uses expires. A key you give and never use in a migration is kept for 24 hours, then removed.
- Plan it again copies the keys. A migration planned again from a rolled back, failed or stopped one gets its own copy of each key. Closing either migration never removes the other's keys.
- A key that no longer works says so. When the tool no longer holds a key, or the site no longer accepts it, Copy again, Check again, a final sync, a rollback, a load and Carry on each say so in plain words and offer Give the migration a new key. Give a new key for the same site and carry on: nothing the migration has done is lost. A key the tool kept the old way, before October 15, 2026, is treated as expired: it is destroyed and asked for again.
- A key Insites could not check just then. If Insites briefly cannot check a key, the tool waits and tries again by itself. If it still cannot, it says the site could not check the key just then: nothing was changed, so try again in a minute.
- When they go. The keys are removed when you close the migration on the Close step, when the workspace or account is closed, or when you press Remove the keys now on the run's Key page, which keeps the migration open. They also go when nothing has happened on the migration for 90 days, after an email to whoever started it 14 days before. That too keeps the migration open: give it a new key when you next need one.
Removing the tool's copy does not revoke an access token: Console does that. More on keys and data.