Skip to main content
Theme

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.

InstanceThe keyWhere 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

  1. Sign in to Insites Console and open the new instance.
  2. Open the CLI tab. The Access Token card is the last one on the tab. Press Get my token.
  3. Copy the token. It starts iak_.
  4. 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.io or staging-insites.io. Not the site's public domain: until the cutover, it still opens the old site.
You need the Developer role on the instance. 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 instance 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 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.io or staging-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.

An Insites v4 instance. Choose Insites v4 as the source. It connects the same two ways, through the Insites v5 Console, with one difference: a v4 instance has no /admin/api page, so find its UUID in the Insites v5 Console, on the instance's details. Insites v4.
The v5 Console, not the v6 one. 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

  1. 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 tries console.insites.io, which no longer signs in a v5 instance.
  2. Find the instance's UUID. Open https://your-instance/admin/api: it is in the Instance Details table.
  3. In an empty folder, run:
    insites-cli env add old-site --email [email protected] --instance-uuid THE-UUID
    Enter your Insites v5 Console password when it asks.
  4. Open the .insites file the command wrote in that folder. The admin key is the value of key under old-site.
  5. 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.

Connected with a password before version 0.5.0? Before version 0.5.0 the tool kept a v5 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 Insites v5 Console email and password once. Nothing the migration has done is lost.
Not the REST API key. The key you see under Integrations in an instance'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 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.

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 instance, 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:

  1. The job names each form or page that checks reCAPTCHA, with the page it is on and its file.
  2. 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.
  3. 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.
  4. 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.
  5. 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.