Skip to main content
This page explains the two supported ways to register a new device (agent) with your Insaion workspace:
  • Manual pairing using a short-lived pairing token (good for single devices and testing).
  • Enrollment keys created under Settings > Enrollment Keys (persistent keys for automated and bulk installs).
Both methods end with the agent authenticating to the Insaion backend and the device appearing on the Devices page. Choose the approach that fits your deployment: use pairing tokens for one-off or developer machines, and enrollment keys for production fleets and automated installs.

​
Pairing token

The pairing token is a short-lived token generated from the dashboard when you choose Manual Pairing on the Add new device page. It is intended for interactive, single-device registration and expires after a short period. Treat pairing tokens like one-time secrets: copy and paste them only into the device UI and do not store them in public locations. When to use
  • Setting up a single robot or test device.
  • Demonstrations and debugging where you want to manually confirm the device identity.
Steps
  1. In the Insaion dashboard go to Devices → Add device and choose Manual Pairing (or click Add device then Manual Pairing).
  2. Click Generate Pairing Token and copy the token that appears. Note: tokens are time-limited. Pairing token dialog
  3. On the target device start the agent (see the Agent installation page):
start-agent.sh
  1. Open the agent’s local web UI on the robot: http://localhost:9090 or http://[ROBOT_IP]:9090. Agent local UI
  2. Paste the pairing token into the Manual Pairing field and click Register.
  3. If the token is valid the agent will register and the device will appear on the Devices page.
Security notes
  • Pairing tokens are ephemeral and should be used only interactively. They are not suitable for automated deployments.
  • If a token is accidentally exposed, it will expire quickly; there is no additional secret to rotate for this method.

​
Enrollment key

Enrollment keys are persistent secrets that you create and manage under Settings → Enrollment Keys. They are designed for automated and bulk device registration during agent install or startup (for example, as part of a bootstrap script or container environment). Enrollment keys are treated like API keys: protect them, rotate them periodically, and scope or label them so you can audit which batch of devices used which key. When to use
  • Automated provisioning of many devices or robots.
  • CI/CD or image-based installs where the agent should register itself without human intervention.
Steps
  1. In the Insaion dashboard go to Settings → Enrollment Keys and create a new enrollment key. Optionally add a descriptive name to track its purpose.
  2. Copy the key value (store it securely; treat it as a secret). Note that the key will only be shown once at creation. Create enrollment key
  3. On the target device set the environment variable and start the agent. Example:
export ENROLLMENT_KEY="your-enrollment-key-here"
start-agent.sh
  1. The agent will use the enrollment key to authenticate and register automatically. The device should appear in the Devices page shortly after successful registration.

​
Troubleshooting

  • Enrollment key rejected: verify you copied the key exactly and that the key is still active (not revoked or expired).
  • Automated install not registering: confirm the ENROLLMENT_KEY is visible to the agent process and that the agent can reach the Insaion backend over the network.
  • Check agent logs for detailed error messages about enrollment or connectivity.

​
Security and lifecycle

  • Treat enrollment keys like secrets. Store them in a secrets manager or environment variables that are not checked into source control.
  • Rotate keys periodically and revoke keys that are no longer needed. After revocation, devices that registered with a revoked key will continue to operate normally; revocation prevents new enrollments with that key.
  • Use descriptive names when creating keys so you can identify which deployment or image used each key.

​
Differences at a glance

  • Pairing token: short-lived, single-use style flow. Best for manual, interactive registration and debugging.
  • Enrollment key: persistent, intended for automated or bulk registration. Best for production fleets and scripted installs.

​
Best practices

  • Use enrollment keys for production deployments; label and rotate them regularly.
  • Use pairing tokens for development, testing, or when you must avoid embedding a secret on the device.
  • Limit distribution of keys and tokens. Prefer ephemeral tokens when handing a device temporarily to an external contractor.
  • Monitor and audit the Devices page and enrollment key usage regularly.