Skip to main content

​
Overview

The Link UI supports advanced configuration through query parameters that allow you to customize the user experience, pre-select options, and control the authentication flow. This guide covers all available query parameters and their use cases.

​
Query Parameters Reference

​
Environment Control

​
sandbox

Controls whether the Link UI runs in sandbox or live mode. Values:
  • true or 1 - Enables sandbox mode
  • Omitted or false - Uses live mode (default)
Example: 
https://auth.amps.ai/{appId}?sandbox=true
Use Case: Use sandbox mode for testing and development. Live mode is for production connections.

​
Device Type Pre-Selection

​
deviceType

Pre-selects the device type, skipping the device type selection step. Values:
  • battery - Battery storage systems
  • hvac - Heating, ventilation, and air conditioning
  • ev_charger - Electric vehicle charging stations
  • solar_inverter - Solar panel inverter systems
  • vehicle - Electric vehicles
Example: 
https://auth.amps.ai/{appId}?deviceType=battery
Use Case: When your application only supports specific device types, pre-filter to show only relevant OEMs.

​
User Identification

​
externalUserRef

Maps devices to a user identifier in your system. This parameter determines whether users are identified or anonymous. Behavior:
  • If you provide a valid email: The user is treated as identified and can be tracked across sessions
    • Example: ?externalUserRef=user@example.com → Uses user@example.com as the identifier
  • If omitted or invalid: The system auto-generates a unique user_ prefixed ID (e.g., user_abc123xyz), and the user is treated as anonymous
Format:
  • Valid email address (1-100 characters)
  • If not provided or invalid, system generates: user_{random_id}
Example (Identified User): 
https://auth.amps.ai/{appId}?externalUserRef=user@example.com
Example (Anonymous User): 
https://auth.amps.ai/{appId}
Use Cases:
  • Identified users: When you know the user’s email and want to link devices across sessions
  • Anonymous users: For guest flows or when user identification isn’t required
Use email addresses for identified users when you want to track device connections across sessions. Anonymous users get a unique ID generated per session.

​
Device Selection Control

​
skipDeviceSelection

Automatically selects all discovered devices, skipping the device selection step. Values:
  • true or 1 - Auto-selects all devices
  • Omitted or false - Shows device selection step (default)
Example: 
https://auth.amps.ai/{appId}?skipDeviceSelection=true
Use Case: When you want to connect all available devices without user interaction.
Using skipDeviceSelection=true will automatically connect all devices found. Make sure this aligns with your user experience expectations.

​
maxDevices

Limits the maximum number of devices a user can select during the device selection step. Values:
  • Integer between 1 and 100
  • Omitted - No limit (default)
Example: 
https://auth.amps.ai/{appId}?maxDevices=1
Use Cases:
  • Single device selection: Set maxDevices=1 to force users to select only one device
  • Limited selection: Restrict selection to a specific number (e.g., maxDevices=5)

​
Parameter Combinations

​
Common Use Cases

​
Single Device Selection for Batteries

https://auth.amps.ai/{appId}?deviceType=battery&maxDevices=1

​
Auto-connect All Devices for Identified User

https://auth.amps.ai/{appId}?externalUserRef=user@example.com&skipDeviceSelection=true

​
Sandbox Testing with Pre-selected Device Type

https://auth.amps.ai/{appId}?sandbox=true&deviceType=hvac

​
Best Practices

Use email addresses when:
  • You have authenticated users in your system
  • You want to track device connections across sessions
  • You need to link devices to specific user accounts
Let it auto-generate when:
  • Building guest/anonymous flows
  • User identification isn’t required
  • Testing or prototyping
  • Single device: Use maxDevices=1 for applications that only support one device per user
  • Multiple devices: Omit maxDevices or set a reasonable limit based on your use case
  • Auto-select: Use skipDeviceSelection=true only when connecting all devices is the desired behavior
Always use deviceType when your application only supports specific device types. This improves UX by showing only relevant OEMs.
Always use sandbox=true during development and testing. Remove it or set to false for production.

​
Troubleshooting Parameters

  • Verify parameter names are spelled correctly
  • Check that boolean values use true or 1 (not True or yes)
  • Confirm deviceType uses exact values: battery, hvac, ev_charger, solar_inverter, vehicle
  • Verify skipDeviceSelection=true (not skipDeviceSelection=1 for some systems)
  • Check that devices were actually discovered (no devices = no selection step)
  • Verify externalUserRef is a valid email format
  • Check that the parameter is properly URL-encoded if passed programmatically
  • Ensure the email isn’t being truncated or modified

​
Next Steps

Getting Started with Link UI

Learn the basics of Link UI

API Authentication

Learn how to authenticate your API requests

Environments Guide

Learn about Sandbox and Live environments

API Reference

Explore API endpoints