How-to
Get the key for each instance
A migration needs a key for each instance: one for the new v6 instance it copies to, and one for the old instance it copies from. The tool reads and writes through each instance's admin API, which is the only way to copy rows with their original ids and dates.
| Instance | The key | Where it goes in the tool |
|---|---|---|
| The new v6 instance (the destination) | A Console access token, from its CLI tab. A GraphQL admin key works too. | Destination, Connect |
| The old v5 instance (the source) | Its GraphQL admin key, or your Insites v5 Console email and password with the instance UUID. | Source, Connect |
The new v6 instance: an access token from Console
- Sign in to Insites Console and open the new instance.
- 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 instance's address into v6 instance URL and paste the token into Console access token. The tool works out which instance the token opens from the address. Use the instance'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.
When you connect, the tool also checks that the token is for the instance at the address you typed. A token copied from a different instance is refused. If the new instance 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 instance 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 instances on the Insites private stack, at addresses ending
prod01-insites.ioorstaging-insites.io. Every new v6 instance is one.
The old Insites v5 instance
A v5 instance has no access token. There are two ways to connect it: its GraphQL admin key, or your Insites v5 Console sign-in. Use one, not both: if you fill in both, the tool asks you to clear one. Connect the live (production) instance, not a UAT or staging copy, because the final sync copies the changes made on it.
/admin/api page, so find its UUID in the Insites v5 Console, on the instance's details. Insites v4.console.insites.io now opens the Insites v6 Console, which is where you get the new instance's access token. A v5 instance is still reached through the Insites v5 Console, so both ways below use your Insites v5 Console sign-in: the email and password you used for the old instance. The tool knows where the v5 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. Version 6.3.1 or later signs in to the Insites v5 Console. An older version triesconsole.insites.io, which no longer signs in a v5 instance. - Find the instance's UUID. Open
https://your-instance/admin/api: it is in the Instance Details table. - In an empty folder, run:
Enter your Insites v5 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 Insites v5 Console password. If your v5 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 instance's GraphQL admin key, and paste that.
Way 2: your Insites v5 Console sign-in, without the CLI
Leave the GraphQL admin key empty and fill in all three of these instead:
- Instance UUID: in the Insites v5 Console, or the Instance Details table at
https://your-instance/admin/api. - Insites v5 Console email: the email you sign in to the Insites v5 Console with.
- Insites v5 Console password: your Insites v5 Console password. Not your v6 Console sign-in.
When you connect, the tool signs in to the Insites v5 Console once for you, the way the CLI does, and gets the instance'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 v5 Console does not accept them, the tool says so before anything is kept.
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 instance's secret key cannot be read through its admin API, the new instance'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 instance draws it with its own key.
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 instance'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 instance with that site key and secret key, and ask how to send the secret key safely. A version 6 instance 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 instance on October 24, 2026.
- Or, with no keys at all, switch each one to the platform's hCaptcha, which the new instance 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 instance 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 instance 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 instance 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 instance 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.