> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amps.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Link UI Customization

> Tune the Link UI flow with query parameters: sandbox, deviceType, externalUserRef, skipDeviceSelection, and maxDevices.

## Overview

Link UI accepts query parameters that pre-select options, identify users, and bound device selection. Combine them on the `auth.amps.ai/{appId}` URL to tailor the flow for specific integrations.

## 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

<Tip>
  Use email addresses for identified users when you want to track device connections across sessions. Anonymous users get a unique ID generated per session.
</Tip>

***

### 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.

<Warning>
  Using `skipDeviceSelection=true` will automatically connect all devices found. Make sure this aligns with your user experience expectations.
</Warning>

***

#### `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

<AccordionGroup>
  <Accordion title="When to use externalUserRef">
    **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
  </Accordion>

  <Accordion title="Device selection strategies">
    * **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
  </Accordion>

  <Accordion title="Pre-filtering device types">
    Always use `deviceType` when your application only supports specific device types. This improves UX by showing only relevant OEMs.
  </Accordion>

  <Accordion title="Environment management">
    Always use `sandbox=true` during development and testing. Remove it or set to `false` for production.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting Parameters

<AccordionGroup>
  <Accordion title="Parameters not working">
    * 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`
  </Accordion>

  <Accordion title="Device selection still showing">
    * Verify `skipDeviceSelection=true` (not `skipDeviceSelection=1` for some systems)
    * Check that devices were actually discovered (no devices = no selection step)
  </Accordion>

  <Accordion title="User not identified">
    * 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
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Getting Started with Link UI" icon="link" href="/guides/link-ui/getting-started">
    Learn the basics of Link UI
  </Card>

  <Card title="API Authentication" icon="key" href="/get-started/authentication">
    Learn how to authenticate your API requests
  </Card>

  <Card title="Environments Guide" icon="info" href="/get-started/environments">
    Learn about Sandbox and Live environments
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore API endpoints
  </Card>
</CardGroup>